.. _rolereference:

Role Reference

==============

Common parameters

-----------------

A number of common parameters are used by all of the roles during

deployment. This section lists such parameters.

**tls_private_key_dir** (string, optional if paths to private keys for all roles are explicitly specified)

  Path to directory on Ansible host that contains the private keys used by

  services deployed by various roles. When TLS key path is not explicitly

  defined in a role, this is the directory where the TLS key will be looked-up

  during Ansible run. Expected filename pattern is ``FQDN_SERVICE.key`` (for

  example, ``mail.example.com_smtp.key`` or ``xmpp.example.com_xmpp.key``).

**tls_certificate_dir** (string, optional if paths to certificate files for all roles are explicitly specified)

  Path to directory on Ansible host that contains the X.509 certificate files

  used by services deployed by various roles. When X.509 certificate path is not

  explicitly defined in a role, this is the directory where the X.509

  certificate will be looked-up during Ansible run. Expected filename pattern is

  ``FQDN_SERVICE.pem`` (for example, ``mail.example.com_smtp.pem`` or

  ``xmpp.example.com_xmpp.pem``).

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

    - ../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, optional, ``[]``)

  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 ``misc`` LDAP schema (from ``/etc/ldap/schema/misc.ldif``). This

  is necessary for the mail server role.

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

* Creates a basic directory structure used by most of the other roles.

* Creates a basic directory structure used by the mail server role.

* Creates login entries for services that need to consume LDAP directory data in

  some way.

* Creates user-supplied groups in LDAP.

* Configures permissions.

* Creates LDAP entries.

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

* Sets the LDAP server administrator's password.

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

---

ldap_entries: []

ldap_server_domain: "{{ ansible_domain }}"

# Internal value, base DN.

ldap_server_int_basedn: "{{ ldap_server_domain | regex_replace('\\.', ',dc=') | regex_replace('^', 'dc=') }}"

ldap_server_organization: "Private"

ldap_server_log_level: 256

ldap_server_tls_certificate: "{{ tls_certificate_dir }}/{{ ansible_fqdn }}_ldap.pem"

ldap_server_tls_key: "{{ tls_private_key_dir }}/{{ ansible_fqdn }}_ldap.key"

ldap_server_ssf: 128

ldap_server_consumers: []

ldap_server_groups: []

ldap_permissions:

  - >

    to *

    by dn.exact=gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth manage

    by dn="cn=admin,{{ ldap_server_int_basedn }}" manage

    by * break

  - >

    to attrs=userPassword,shadowLastChange

    by self write

    by anonymous auth

    by * none

  - >

    to dn.base=""

    by * read

  - >

    to *

    by self write

    by dn="cn=admin,{{ ldap_server_int_basedn }}" write

    by users read

    by * none

---

dependencies:

- name: Enable the memberof overlay for database

  ldap_entry:

    dn: "olcOverlay={0}memberof,olcDatabase={1}mdb,cn=config"

    objectClass:

      - olcConfig

      - olcMemberOf

      - olcOverlayConfig

    olcOverlay: memberof

    olcMemberOfRefInt: "TRUE"

    olcMemberOfGroupOC: groupOfUniqueNames

    olcMemberOfMemberAD: uniqueMember

- name: Apply database permissions

  ldap_permissions:

    filter: "(olcSuffix={{ ldap_server_int_basedn }})"

    rules: "{{ ldap_permissions }}"

- name: Create basic LDAP directory structure

  ldap_entry: ""

  args:

    dn: "ou={{ item }},{{ ldap_server_int_basedn }}"

    objectClass:

      - organizationalUnit

    ou: "{{ item }}"

  with_items:

    - people

    - groups

    - services

- name: Create the entry that will contain mail service information

  ldap_entry: ""

  args:

    dn: "ou=mail,ou=services,{{ ldap_server_int_basedn }}"

    objectClass: organizationalUnit

    ou: mail

- name: Create LDAP directory structure for mail service

  ldap_entry: ""

  args:

    dn: "ou={{ item }},ou=mail,ou=services,{{ ldap_server_int_basedn }}"

    objectClass: organizationalUnit

    ou: "{{ item }}"

  with_items:

    - domains

    - aliases

- name: Create or remove login entries for services

  ldap_entry: ""

  args:

    dn: "cn={{ item.name }},ou=services,{{ ldap_server_int_basedn }}"

    objectClass:

      - applicationProcess

      - simpleSecurityObject

    cn: "{{ item.name }}"

    userPassword: "{{ item.password }}"

    state: "{{ item.state | default('present') }}"

  with_items: ldap_server_consumers

- name: Create or remove user-supplied groups

  ldap_entry: ""

  args:

    dn: "cn={{ item.name }},ou=groups,{{ ldap_server_int_basedn }}"

    objectClass: groupOfUniqueNames

    cn: "{{ item.name }}"

    uniqueMember: "cn=NONE"

    state: "{{ item.state | default('append') }}"

  with_items: ldap_server_groups

- name: Create user-supplied LDAP entries

  ldap_entry: ""

  args: "{{ item }}"

  with_items: ldap_entries

- name: Deploy firewall configuration for LDAP

  copy: src="ferm_ldap.conf" dest="/etc/ferm/conf.d/10-ldap.conf" owner=root group=root mode=640

  notify:

    - Restart ferm

- name: Deploy temporary file with LDAP admin password

  template: src="ldap_admin_password.j2" dest="/root/.ldap_admin_password"

            owner=root group=root mode=400

  changed_when: False

- name: Test if LDAP admin password needs to be changed

  command: ldapwhoami -D "cn=admin,{{ ldap_server_int_basedn }}" -x -y /root/.ldap_admin_password

  register: ldap_admin_password_check

  changed_when: ldap_admin_password_check.rc != 0

  failed_when: False

- name: Update LDAP admin password

  command: ldappasswd -Y EXTERNAL -H ldapi:/// "cn=admin,{{ ldap_server_int_basedn }}" -T /root/.ldap_admin_password

  when: ldap_admin_password_check.rc != 0

- name: Remove temporary file with LDAP admin password

  file: path="/root/.ldap_admin_password" state=absent

  changed_when: False

---

# Define domain for the test site that should be used.

testsite_domain: example.com

# Derive some additional values that will be used - basing them on domain.

testsite_domain_underscores: "{{ testsite_domain | regex_replace('\\.', '_') }}"

testsite_domain_alternative: "{{ testsite_domain | regex_replace('\\.[^.]+$', '.something') }}"

testsite_ldap_base: "{{ testsite_domain | regex_replace('\\.', ',dc=') | regex_replace('^', 'dc=') }}"

# Configuration for roles bootstrap and preseed.

ansible_key: "{{ lookup('file', '~/.ssh/id_rsa.pub') }}"

# Configuration for role 'common', shared across all servers.

os_users:

  - name: admin

    uid: 1000

    additional_groups:

      - sudo

    authorized_keys:

      - "{{ lookup('file', '~/.ssh/id_rsa.pub') }}"

    password: '$6$/aerscJY6aevRG$ABBCymEDtk2mHW/dklre9dMEdgZNJvVHsGLCzgjGmy61FssZ.KW7ePcO2wsMGIkHcg3mZlrA4dhYh.APq9OQu0'

  - name: johndoe

    uid: 1001

    additional_groups:

      - office

      - developer

    password: '$6$cJnUatae7cMz23fl$O3HE2TslnEaKaTDSZnvuDDrfqILAiuMV1wOPGVnkUQFxUu3gIWZOyO7AI1OWYkqeQMVBiezpSqYNiQy6NF6bi0'

os_groups:

  - name: office

    gid: 1500

  - name: developer

    gid: 1501

common_packages:

  - emacs24-nox

  - screen

  - debconf-utils

  - colordiff

  - unzip

ca_certificates:

  - "{{ inventory_dir }}/tls/ca.pem"

incoming_connection_limit: 2/second

incoming_connection_limit_burst: 6

# Default LDAP client configuration.

ldap_client_config:

  - comment: Set the base DN

    option: BASE

    value: "{{ testsite_ldap_base }}"

  - comment: Set the default URI

    option: URI

    value: ldap://ldap.{{ testsite_domain }}/

  - comment: Set the LDAP TLS truststore

    option: TLS_CACERT

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

  - comment: Enforce TLS

    option: TLS_REQCERT

    value: demand

---

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

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') }}"

---

local_mail_aliases:

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

smtp_relay_host: mail.{{ testsite_domain }}

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

https_tls_key: "{{ inventory_dir }}/tls/web.{{ testsite_domain }}_https.key"

https_tls_certificate: "{{ inventory_dir }}/tls/web.{{ testsite_domain }}_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."

db_root_password: "root"