Role Reference
==============


Preseed
-------

The ``preseed`` role can be used for generating simple preseed files for Debian
Wheezy installations.

The generated preseed files allow simplified installation, with a single root
partition. There is a number of parameters that allow for customising the
content of preseed files.

It is possible to specify parameter values that should be used for all servers,
as well for individual servers. It is also possible to combine this approach,
defining global parameters that get overridden per server.

The role will by default process all hosts from the inventory, generating one
preseed file per server.


Parameters
~~~~~~~~~~

**ansible_key** (string, optional, ``{{ lookup('file', '~/.ssh/id_rsa.pub') }}``)
  SSH public key that should be deployed to authorized_keys truststore for
  operating system user ``root``. This is necessary for the bootstrap process
  to work since Debian Jessie does not allow password-based logins for root.

**preseed_country** (string, optional, ``SE``)
  Country.

**preseed_directory** (string, optional, ``../preseed_files/``)
  Destination directory where the preseed files should be stored.

  .. warning::
     Do not name this directory ``preseed`` if it lies on a path where Ansible
     would normally look-up the roles (it will conflict with the role name).

**preseed_dns** (string, mandatory if **preseed_network_auto** is ``no``)
  Comma-separated list of DNS servers.

**preseed_domain** (string, mandatory if **preseed_network_auto** is ``no``)
  Server domain.

**preseed_gateway** (string, mandatory if **preseed_network_auto** is ``no``)
  Default gateway for the server.

**preseed_hostname** (string, mandatory if **preseed_network_auto** is ``no``)
  Server hostname.

**preseed_ip** (string, mandatory if **preseed_network_auto** is ``no``)
  IP address for the server network interface.

**preseed_keymap** (string, optional, ``us``)
  Keymap.

**preseed_language** (string, optional, ``en``)
  Language.

**preseed_locale** (string, optional, ``en_US.UTF-8``)
  Locale.

**preseed_mirror_directory** (string, optional, ``/debian``)
  Directory under which the Debian apt repositories can be found on the
  specified mirror.

**preseed_mirror_hostname** (string, optional, ``ftp.se.debian.org``)
  Resolvable hostname of FQDN where the Debian apt repositories can be
  found. Only HTTP mirrors are supported.

**preseed_mirror_proxy** (string, optional, ``None``)
  An HTTP proxy that should be used for accessing the Debian apt
  repositories.

**preseed_netmask** (string, mandatory if **preseed_network_auto** is ``no``)
  Netmask for the server network interface.

**preseed_network_auto** (boolean, optional, ``yes``)
  Specifies whether the network configuration should be automatic (using DHCP)
  or manual. If manual configuration is selected a number of additional options
  needs to be specified: ``preseed_hostname``, ``preseed_domain``,
  ``preseed_ip``, ``preseed_netmask``, ``preseed_gateway``,
  ``preseed_dns``. For some of these values you may want to use per-server
  overrides - see parameter ``preseed_server_overrides``.

**preseed_network_interface** (string, optional, ``eth0``)
  Name of network interface (for example ``eth0``, ``eth1`` etc) that should be
  configured.

**preseed_root_password** (string, optional, ``root``)
  Initial password that should be set for the server during the installation.

**preseed_server_overrides** (string, optional, ``{}``)
  A dictionary consisting out of one or more entries where individual values for
  preseed files can be overridden per-server. Each entry's key should be the
  name of the server, as specified in the inventory. Each value should also be a
  dictionary, where valid keys are: ``country``, ``dns``, ``domain``,
  ``gateway``, ``hostname``, ``ip``, ``keymap``, ``language``, ``locale``,
  ``mirror_directory``, ``mirror_hostname``, ``mirror_proxy``, ``netmask``,
  ``network_auto``, ``network_interface``, ``root_password``,
  ``timezone``. These have the same meaning as their ``preseed_`` counterparts.

**preseed_timezone** (string, optional, ``Europe/Stockholm``)
  Timezone that should be used when calculating server time. It is assumed that
  the local hardware clock is set to UTC.


Examples
~~~~~~~~

Here is an example configuration for a preseed file that sets some global
defaults to be used for all servers, and then overrides it for one server:

.. code-block:: yaml

  ---

  ansible_key: /root/ansible/private.key
  preseed_country: UK
  preseed_directory: /var/www/preseed
  preseed_keymap: UK
  preseed_language: en
  preseed_locale: en_UK.UTF-8
  preseed_mirror_directory: /debian
  preseed_mirror_hostname: ftp.uk.debian.org
  preseed_mirror_proxy: ""
  preseed_network_auto: yes
  preseed_network_interface: eth0
  preseed_root_password: secret
  preseed_timezone: Europe/London
  preseed_server_overrides:
    ldap.example.com:
      network_auto: no
      hostname: ldap
      domain: example.com
      ip: 192.168.1.20
      netmask: 255.255.255.0
      gateway: 192.168.1.1
      dns: 192.168.1.1,192.168.1.2
      timezone: Europe/Stockholm


Bootstrap
---------

The ``bootstrap`` role can be used for bootstraping a new server with
Ansible. In order to apply this role to a server, all that is necessary is root
access to the server (either via SSH or locally).

The role implements the following:

* Installs sudo package.
* Creates operating system user and group for Ansible (``ansible``).
* Sets-up an authorized_key for operating system user ``ansible`` (for remote
  SSH access).
* Configures sudo to allow operating system user ``ansible`` to run sudo
  commands without password authentication.
* Removes the Ansible user's key from the list of authorized keys for user root
  at the end of bootstrap process. This key was necessary only for the bootstrap
  process.


Parameters
~~~~~~~~~~

**ansible_key** (string, mandatory)
  SSH public key that should be deployed to authorized_keys truststore for
  operating system user ``ansible``.


Examples
~~~~~~~~

Since the role is meant to be used just after the server has been installed, and
using the ``root`` account, it is probably going to be invoked from a separate
playbook.

For example, a playbook (``bootstrap.yml``) could look something similar to:

.. code-block:: yaml

  ---

  - hosts: "{{ server }}"
    remote_user: root
    roles:
      - bootstrap
    vars:
      ansible_key: "{{ lookup('file', 'authorized_keys/ansible.pub') }}"

With such a playbook in place, it would be invoked with:

  ansible-playbook --ask-pass -e server=test1.example.com bootstrap.yml


Common
------

The ``common`` role can be used for applying a common configuration and
hardening across all servers, no matter what services they provide.

The role implements the following:

* Configures apt to use caching proxy (if any was specified).
* Sets-up umask for all logins to ``0027``.
* Installs sudo.
* Installs additional base packages, as configured.
* Creates additional operating system groups, as configured.
* Creates additional operating system users, as configured.
* Hardens the SSH server by disabling remote ``root`` logins and password-based
  authentication.
* Allows traversing of directory ``/etc/ssl/private/`` to everyone. This lets
  you put TLS private keys in central location where any operating system user
  can reach them provided they have appropriate read/write rights on the file
  itself, and provided they know the exact path of the file.
* Deploys CA certificate files, normally used for truststore purposes, to
  ``/etc/ssl/certs/``.
* Installs ``ferm`` (for iptables management), configuring a basic firewall
  which allows ICMP echo requests (PING), incoming connection on TCP port 22
  (SSH), and also introduces rate-limitting for incoming ICMP echo request
  pacakges and (new) TCP connections. The rate-limitting is based on the source
  IP address, using the ``iptables hashlimit`` module.


Parameters
~~~~~~~~~~

**apt_proxy** (string, optional, ``None``)
  URI of a caching proxy that should be used when retrieving the packages via
  apt.

**os_users** (list, optional, ``[]``)
  A list of operating system users that should be set-up on a server. Each item
  is a dictionary with the following options describing the user parameters:

  **name** (string, mandatory)
    Name of the operating system user that should be created. User's default
    group will have the same name as the user.

  **uid** (number, optional, ``whatever OS picks``)
    UID for the operating system user. User's default group will have a GID
    identical to the user's UID if specified. Otherwise user's default group
    will have OS-determined GID.

  **additional_groups** (list, optional, ``[]``)
    Comma-separated list of additional groups that a user should belong to.

  **authorized_keys** (list, optional, ``[]``)
    List of SSH public keys that should be deployed to user's authorized_keys
    truststore.

  **password** (string, optional, ``!`` - no password)
    Encrypted password that should be set for the user.

**os_groups** (list, optional, ``[]``)
  A list of operating system groups that should be set-up on a server. Each item
  is a dictionary with the following options describing the group parameters:

  **name** (string, mandatory)
    Name of the operating system group that should be created.

  **gid** (number, optional, ``whatever OS picks``)
    GID for the operating system group.

**common_packages** (list, optional, ``[]``)
  List of additional operating system packages that should be installed on the
  server. Each element of the list should be a simple string denoting the name
  of the package.

**ca_certificates** (list, optional, ``[]``)
  List of additional CA certificate files that should be deployed on the
  server. Each element of the list should be a filepath to a CA certificate file
  on originating (Ansible) host that should be copied to destination
  server.

**incoming_connection_limit** (string, optional, ``3/second``)
  Rate at which the incoming ICMP echo-request packages and new TCP connections
  will be accepted at. The value should be specified in the same format as value
  for the ``iptables hashlimit`` option ``--hashlimit-upto``.

**incoming_connection_limit_burst** (string, optional, ``9``)
  Initial burst of packages that should be accepted when the client with
  distinct source IP address connects to the server for the first time (usually
  higher than ``incoming_connection_limit``), even if it would go above the
  specified connection limit.


Examples
~~~~~~~~

Here is an example configuration for setting-up some common users, groups, and
packages on all servers:

.. code-block:: yaml

  ---

  os_users:
    - name: admin
      uid: 1000
      additional_groups:
        - sudo
      authorized_keys:
        - "{{ lookup('file', '/home/admin/.ssh/id_rsa.pub') }}"
      password: '$6$AaJRWtqyX5pk$IP8DUjgY0y2zqMom9BAc.O9qHoQWLFCmEsPRCika6l/Xh87cp2SnlMywH0.r4uEcbHnoicQG46V9VrJ8fxp2d.'
    - name: john
      uid: 1001
      password: '$6$AaJRWtqyX5pk$IP8DUjgY0y2zqMom9BAc.O9qHoQWLFCmEsPRCika6l/Xh87cp2SnlMywH0.r4uEcbHnoicQG46V9VrJ8fxp2d.'

  os_groups:
    - name: localusers
      gid: 2500

  common_packages:
    - emacs23-nox
    - screen
    - debconf-utils

  ca_certificates:
    - ../certs/truststore.pem

  incoming_connection_limit: 2/second

  incoming_connection_limit_burst: 6

.. _ldap_client:

LDAP Client
-----------

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

The role implements the following:

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


Parameters
~~~~~~~~~~

**ldap_client_config** (list, mandatory)
  A list of configuration options that should be put into the LDAP configuration
  file. Each item is a dictionary with the following options defining the
  configuration parameter:

  **comment** (string, mandatory)
    Comment that will be shown in the file just above the configuration option.

  **option** (string, mandatory)
    Name of configuration option.

  **value** (string, mandatory)
    Value for configuration option.


Examples
~~~~~~~~

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

.. code-block:: yaml

  ---

  ldap_client_config:
    - comment: Set the base DN
      option: BASE
      value: dc=example,dc=com
    - comment: Set the default URI
      option: URI
      value: ldap://ldap.example.com/
    - comment: Set the truststore for TLS/SSL
      option: TLS_CACERT
      value: /etc/ssl/certs/example_ca.pem
    - commment: Force basic server certificate verification
      option: TLS_REQCERT
      value: demand
    - comment: Disable CRL checks for server certificate
      option: TLS_CRLCHECK
      value: none


LDAP Server
-----------

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

The role implements the following:

* Deploys LDAP TLS private key and certificate.
* 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_server_config** (list, mandatory)
  A dictionary of configuration options for OpenLDAP server. The following
  configuration options are available:

  **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). I.e. ``example.com`` would get
    transformed into ``dc=example,dc=com``.

  **organization** (string, mandatory)
    Organization that should be specified in the base DN entry.

  **log_level** (string, mandatory)
    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.

  **tls_certificate** (string, mandatory)
    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/``.

  **tls_key** (string, mandatory)
    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/``.

  **ssf** (number, mandatory)
    Minimum *Security Strength Factor* to require from all incoming
    connections. This applies for both remote and local connections.

**ldap_permissions** (list, mandatory)
  List of LDAP access controls to apply to directories served by the LDAP
  server. Each item is a dictionary with the following options describing the
  permissions:

  **filter** (string, mandatory)
    An LDAP filter that should be applied on base DN ``cn=config`` using
    sub-tree scope to locate the LDAP database for which the access control
    rules will be applied. For default user database this could be something in
    the lines of ``(olcSuffix=dc=example,dc=com)``.

  **rules** (list, mandatory)
    A list of access control rules that should be applied for the selected
    database. The access control rules listed 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>`.

**ldap_entries** (list, mandatory)
  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.


Examples
~~~~~~~~

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

.. code-block:: yaml

  ---

  ldap_server_config:
    domain: "example.com"
    organization: "Example Corporation"
    log_level: 256
    tls_certificate: ~/tls/ldap.example.com_ldap.pem
    tls_key: ~/tls/ldap.example.com_ldap.key
    ssf: 128
  
  ldap_permissions:
    - filter: '(olcSuffix=dc=example,dc=com)'
      rules:
        - >
          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``).

**xmpp_tls_key** (string, mandatory)
  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/``.

**xmpp_tls_certificate** (string, mandatory)
  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, mandatory)
  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, mandatory)
  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, mandatory)
  Scope for performing the LDAP search for obtaining a list of users available
  on the Prosody server.

**xmpp_ldap_tls** (boolean, mandatory)
  Specifies whether to use STARTTLS extension when connecting to the LDAP server
  or not.

**xmpp_ldap_base** (string, mandatory)
  Base DN under which the lists of users available on the Prosody should be
  looked-up.


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_tls: "true"
  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, mandatory)
  Path to TLS truststore used for verifying the LDAP certificate. Should be in
  PEM format.

**mail_ldap_root_dn** (string, mandatory)
  Root DN in LDAP under where 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, mandatory)
  Name of the user that owns all the mail files.

**mail_user_uid** (integer, mandatory)
  UID of the user that owns all the mail files.

**mail_user_gid** (integer, mandatory)
  GID of the user that owns all the mail files.

**imap_tls_certificate** (string, mandatory)
  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, mandatory)
  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, mandatory)
  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, mandatory)
  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, mandatory)
  Character used for separating the IMAP folders when clients are requesting
  listing from the server. Usually either slash(``/``) or dot(``.``).

**smtp_rbl** (list, mandatory)
  List of RBLs to use for detecting servers which send out spam. Each item is a
  string resembling the RBL domain.

**mail_postmaster** (string, mandatory)
  Mail address to use for the postmaster account in Dovecot.

**smtp_allow_relay_from** (list, mandatory)
  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, mandatory)
  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, mandatory)
  SMTP server via which the mails are sent out for non-local recipients.

**smtp_relay_truststore** (string, mandatory)
  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
~~~~~~~~~~

**https_tls_key** (string, mandatory)
  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/``.

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

**web_default_title** (string, mandatory)
  Title for the default web page shown to users (if no other vhosts were matched).

**web_default_message** (string, mandatory)
  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)
  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/``.

**php_file_regex** (string, optional)
  Regular expression used for determining which file should be interepted via
  PHP. Default is ``\.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, mandatory)
  UID/GID (they are set-up to be the same) of the dedicated website
  user/group.


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
      admin: admin
      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: "{{ inventory_dir }}/tls/cloud.example.com_https.key"
      https_tls_certificate: "{{ inventory_dir }}/tls/cloud.example.com_https.pem"
    - role: php_website
      admin: admin
      deny_files_regex:
        - ^\..*
      php_rewrite_urls:
        - ^(.*) /index.php?url=$1
      fqdn: tbg.example.com
      uid: 2007
      https_tls_key: "{{ inventory_dir }}/tls/tbg.example.com_https.key"
      https_tls_certificate: "{{ 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 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.
* 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:

* 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``).
* 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. The virtual environment is also symlinked to
  website admin's ``~/.virtualenvs/`` directory for easier access (and
  auto-completion with virtualenvwrapper).
* 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.


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.

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

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

**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, mandatory)
  UID/GID (they are set-up to be the same) of the dedicated website
  user/group.

**use_paste** (boolean, optional)
  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 PHP
  appliction. This is usually going to be different PHP extensions.

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


Examples
~~~~~~~~

Here is an example configuration for setting-up a (base) WSGI website (for
running a bare Django project):

.. code-block:: yaml

    - role: wsgi_website
      admin: admin
      fqdn: django.example.com
      static_locations:
        - /static
        - /media
      uid: 2004
      virtualenv_packages:
        - django
      wsgi_application: django_example_com.wsgi:application
      https_tls_key: "{{ inventory_dir }}/tls/wsgi.example.com_https.key"
      https_tls_certificate: "{{ inventory_dir }}/tls/wsgi.example.com_https.pem"


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 password for the database root user.
* Deploys MariaDB client configuration in location ``/root/.my.cnf`` that
  contains username and password for the root database user.


Parameters
~~~~~~~~~~

**db_root_password** (string, mandatory)
  Password for the *root* database user.


Examples
~~~~~~~~

Here is an example configuration for setting-up the database server:

.. code-block:: yaml

   ---

   db_root_password: root


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.


Parameters
~~~~~~~~~~

**db_name** (string, mandatory)
  Name of the database that should be created.

**db_password** (string, mandatory)
  Password for the database user.


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