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. A number of common parameters can be provided.


Parameters
~~~~~~~~~~

**preseed_directory** (mandatory)
    Destination directory where the preseed files should be stored.

**preseed_servers** (mandatory)
  List of servers for which a preseed file should be created. Each item in
  this list defines options for a single server. The options are as follows:

  **name** (string, mandatory)
    Name associated with the server. This name is used in the preseed
    configuration filename.

  **language** (string, mandatory)
    Language.

  **country** (string, mandatory)
    Country.

  **locale** (string, mandatory)
    Locale.

  **keymap** (string, mandatory)
    Keymap.

  **network_interface** (string, mandatory)
    Name of network interface (for example *eth0*) that should be
    configured.

  **network_auto** (boolean, mandatory)
    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.

  **network_ip** (string, mandatory if **network_auto** is set to ``no``)
    IP address for the server network interface.

  **network_netmask** (string, mandatory if **network_auto** is set to ``no``)
    Netmask for the server network interface.

  **network_gateway** (string, mandatory if **network_auto** is set to ``no``)
    Default gateway for the server.

  **network_dns** (string, mandatory if **network_auto** is set to ``no``)
    Comma-separated list of DNS servers.

  **network_hostname** (string, mandatory if **network_auto** is set to ``no``)
    Server hostname.

  **network_domain** (string, mandatory if **network_auto** is set to ``no``)
    Server domain.

  **mirror_hostname** (string, mandatory)
    Resolvable hostname of FQDN where the Debian apt repositories can be
    found. Only HTTP mirrors are supported.

  **mirror_directory** (string, mandatory)
    Directory under which the Debian apt repositories can be found on the
    specified mirror.

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

  **root_password** (string, mandatory)
    Initial password that should be set for the server during the
    installation.

  **timezone** (string, mandatory)
    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 for two servers, one with
automatic and one with manual network configuration:

.. code-block:: yaml

  ---

  preseed_directory: /var/www/preseed/

  preseed_servers:
    - name: test1.example.com
      language: en
      country: SE
      locale: en_US.UTF-8
      keymap: us
      network_interface: eth0
      network_auto: yes
      mirror_hostname: ftp.se.debian.org
      mirror_directory: /debian
      mirror_proxy: http://proxy.example.com/
      root_password: testserver
      timezone: Europe/Stockholm
    - name: test2.example.com
      language: en
      country: SE
      locale: en_US.UTF-8
      keymap: us
      network_interface: eth0
      network_auto: no
      network_ip: 10.0.0.10
      network_netmask: 255.255.255.0
      network_gateway: 10.0.0.1
      network_dns: 10.0.0.2,10.0.0.3
      network_hostname: test1
      network_domain: example.com
      mirror_hostname: ftp.se.debian.org
      mirror_proxy: http://proxy.example.com/
      mirror_directory: /debian
      root_password: testserver
      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.


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:

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


Parameters
~~~~~~~~~~

**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, mandatory)
    UID for the operating system user. User's default group will have a GID
    identical to the user's UID.

  **additional_groups** (string, mandatory)
    Comma-separated list of additional groups that a user should belong to. If
    no additional groups should be appended to user's list of groups, set it to
    empty string (``""``).

  **authorized_keys** (list, mandatory)
    List of SSH public keys that should be deployed to user's authorized_keys
    truststore. If no authorized keys should be deployed, set it to empty list
    (``[]``).

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


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
      additional_groups: ""
      authorized_keys: []
      password: '$6$AaJRWtqyX5pk$IP8DUjgY0y2zqMom9BAc.O9qHoQWLFCmEsPRCika6l/Xh87cp2SnlMywH0.r4uEcbHnoicQG46V9VrJ8fxp2d.'

  os_groups:
    - name: localusers
      gid: 2500

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


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

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


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 *X.509* certificate (on server itself) that should be used as server
    certificate for TLS connections. The certificate file should be provided in
    ``PEM`` format. If file does not exist, no TLS will be set-up.

  **tls_key** (string, mandatory)
    Path to private key (on server itself) that should be used as server's
    private key for TLS connections. The private key should correspond to
    certificate listed in option ``tls_certificate``. The key file should be
    provided in ``PEM`` format. If file does not exist, no TLS will be set-up.

  **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: /etc/ssl/certs/ldap.example.com.pem
    tls_key: /etc/ssl/private/ldap.example.com.pem
    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


Prosody
-------

The ``prosody`` 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.
* Installs Prosody.
* Configures Prosody.

Prosody is configured as follows:

* Modules enabled: roster, saslauth, tls, dialback, posix, private, vcard,
  version, uptime, time, ping, pep, register, admin_adhoc, announce.
* Self-registration is not allowed.
* TLS is configured.
* 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
~~~~~~~~~~

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

**prosody_tls_key** (string, mandatory)
  Path to private key (on server itself) that should be used as server's private
  key for TLS connections. The private key should correspond to certificate
  listed in option ``prosody_tls_certificate``. The key file should be provided
  in ``PEM`` format.

**prosody_tls_certificate** (string, mandatory)
  Path to *X.509* certificate (on server itself) that should be used as server
  certificate for TLS connections. The certificate file should be provided in
  ``PEM`` format.

**prosody_domains** (list, mandatory)
  List of domains that are served by this Prosody instance. Each item is a
  string specifying a domain.

**prosody_ldap_server** (string, mandatory)
  Fully qualified domain name, hostname, or IP address of the LDAP server used
  for user authentication and listing.

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

**prosody_ldap_password** (string, mandatory)
  Password used for authenticating to the LDAP server.

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

**prosody_ldap_scope** (string, mandatory)
  Scope for performing the LDAP search for obtaining a list of users available
  on the Prosody server.

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

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