.. _rolereference:

Role Reference

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

Common parameters

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

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

deployment. This section lists such parameters.

**enable_backup** (boolean, optional, ``False``)

  If set to ``True``, and the role supports backups, server will be configured

  for back-up of role's data. See role description for more details on what is

  backed-up and if the option is available. Just keep in mind that if you enable

  this globally, all the roles will be running backup-specific tasks. If the

  option has been enabled, the ``backup_client`` role will be included

  automatically (see the role reference for details on parameters that need to

  be provided in the case).

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, mandatory)

  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 does not allow password-based logins for root.

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

  Country.

**preseed_directory** (string, mandatory)

  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.

Distribution compatibility

~~~~~~~~~~~~~~~~~~~~~~~~~~

Role is compatible with the following distributions:

- Debian 10 (Buster)

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: {{ lookup('file', '~/.ssh/id_rsa.pub') }}

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

Distribution compatibility

~~~~~~~~~~~~~~~~~~~~~~~~~~

Role is compatible with the following distributions:

- Debian 10 (Buster)

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.

* Sets-up uniform bash prompt for all accounts (optionally coloured and with

  identifier). This is useful for distinguishing machines and/or environments.

* Sets-up ability to have user-specific ``/etc/profile.d/`` entries via

  ``$HOME/.profile.d/``.

* Installs additional base packages, as configured.

* Disables ``electric-indent-mode`` in Emacs globally if either the ``emacs24``

  or ``emacs24-nox`` are installed through the role.

* 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

  ``/usr/local/share/ca-certificates/``.

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

* Sets-up system for performing checks on certificates (currently only if they

  expire within less than 30 days). Roles that want their certificates checked

  should deploy a ``.conf`` to directory ``/etc/check_certificate/`` with paths

  to certificate files, one per line. Certificates are checked on

  daily basis, using crontab (resulting in failures being sent out to

  the ``root`` user).

* Deploys ``apticron`` package that performs checks for available package

  upgrades on daily basis. Mails are delivered to local ``root`` account, and

  can be redirected elsewhere via aliases. If using ``mail_forwarder`` or

  ``mail_server`` roles on the same server, aliases can be set-up through them.

* Sets-up system for performing checks on pip requirements

  files. Roles that want their requirements files checked should

  create a sub-directory inside of

  ``/etc/pip_check_requirements_upgrades`` (for Python 2

  applications), or ``/etc/pip_check_requirements_upgrades-py3`` (for

  Python 3 applications), and place ``.txt`` and ``.in`` files inside

  (with same base name). The ``.txt`` files should be standard

  requirements files with fixed versions (the ones installed by the

  role). The ``.in`` files should contain only the top-level packages

  (no dependencies). Avoid hard-coding versions in the ``.in`` file

  unless really needed. For packages where you want to stick to

  stable/LTS version branch, you should be able to use ``~=`` operator

  (for example ``django~=1.8.0``. Checks are implemented via

  `pip-tools <https://github.com/jazzband/pip-tools>`_ and a custom

  script that outputs diffs if upgrades are available. Script is run

  via cronjob on daily basis, and any output will be delivered to

  local ``root`` user.

* Optionally configures time synchronisation using NTP (if

  ``ntp_servers`` parameter is set).

Role dependencies

~~~~~~~~~~~~~~~~~

Depends on the following roles:

* **backup_client**

Backups

~~~~~~~

If the backup for this role has been enabled, the following paths are backed-up:

**/var/log**

  Log files from the system.

**/home**

  Home directory for regular users (this can be changed via role parameters).

**/root**

  Root user's home directory (this can be changed via role parameters).

**/etc/shadow**

  Operating system user passwords.

**/var/mail**

  Local user's mails.

**/var/spool/cron**

  Local user's cronjobs.

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

    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, ``{}``)

  Dictionary containing the CA certificates to deploy. Keys are base filenames

  (**without extension**) to be used when placing a certificate file in

  directory ``/usr/local/share/ca-certificates/``, while values are

  corresponding content to be placed in the file.

**extra_backup_patterns** (list, optional, ``[ "/home", "/root" ]]``)

  List of additional globbing patterns defining additional files or directories

  that should be backed-up.

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

**maintenance** (boolean, optional, ``False``)

  Specifies if maintenance mode should be enabled or not. In

  maintenance mode incoming TCP connections are allowed only from

  explicitly listed hosts (see ``maintenance_allowed_hosts``

  parameter). All ports are covered by this rule, with sole exception

  being the TCP port 22 (SSH). The SSH port is never blocked via

  maintenance mode.

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

  List of hosts that should be allowed to connect to the server when

  in maintenance mode.

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

  List of NTP servers to use for synchronising the time on managed

  machine using NTP. If no time synchronisation should be set-up, set

  to empty list. Default is not to configure time synchronisation.

  If setting this parameter, it is recommended to set the list of

  servers to list shipped by default Debian configuration::

    - "0.debian.pool.ntp.org"

    - "1.debian.pool.ntp.org"

    - "2.debian.pool.ntp.org"

    - "3.debian.pool.ntp.org"

**pip_check_requirements_in** (list, optional, ``[pip, pip-tools, setuptools, wheel]``)

  List of Python package requirements inputs to use for checking for

  package upgrades for the Python 2 virtual environment used to run

  the check itself. For Python 3, see the dedicated parameter

  ``pip_check_requirements_py3`` below.

**pip_check_requirements** (list, optional, ``[click==7.1.2, pip-tools==5.5.0, pip==20.3.4, setuptools==44.1.1, wheel==0.37.1]``)

  List of Python package requirements to install in Python 2 virtual

  environment in order to be able to run the ``pip-tools``

  applications as part of pip requirements upgrade checks. This list

  needs to be updated from time to time as the new releases of

  ``pip-tools`` and related packages are coming out. For Python 3, see

  the dedicated parameter ``pip_check_requirements_py3`` below.

**pip_check_requirements_py3_in** (list, optional, ``[pip, pip-tools, setuptools, wheel]``)

  List of Python package requirements inputs to use for checking for

  package upgrades for the Python 3 virtual environment used to run

  the check itself. For Python 2, see the dedicated parameter

  ``pip_check_requirements`` above.

**pip_check_requirements_py3** (list, optional, ``see below``)

  List of Python package requirements to install in Python 3 virtual

  environment in order to be able to run the ``pip-tools``

  applications as part of pip requirements upgrade checks. This list

  needs to be updated from time to time as the new releases of

  ``pip-tools`` and related packages are coming out. For Python 2, see

  the dedicated parameter ``pip_check_requirements`` above.

  Default value is:

  .. code-block:: yaml

    - build==1.0.3

    - click==8.1.7

    - importlib-metadata==6.7.0

    - packaging==23.2

    - pip-tools==6.14.0

    - pip==23.1.2

    - pyproject-hooks==1.0.0

    - setuptools==68.0.0

    - tomli==2.0.1

    - typing-extensions==4.7.1

    - wheel==0.41.3

    - zipp==3.15.0

**pipreqcheck_uid** (integer, optional, ``whatever OS picks``)

  UID for user running the pip requirements upgrade checks. User is created with

  name ``pipreqcheck``.

**pipreqcheck_gid** (integer, optional, ``whatever OS picks``)

  GID for user running the pip requirements upgrade checks. Group is created

  with name ``pipreqcheck``.

**prompt_colour** (string, optional, ``none``)

  Colour for showing the Bash prompt. Supported values are:

  ``black``, ``red``, ``green``, ``brown``, ``blue``, ``purple``, ``cyan``,

  ``light_gray``, ``dark_gray``, ``light_red``, ``light_green``, ``yellow``,

  ``light_blue``, ``light_purple``, ``light_cyan``, ``white``, ``none``.

  You should probably *not* use the ``black`` colour. Setting affects Bash

  shells *only*. Setting the value to ``none`` uses default terminal colour.

**prompt_id** (string, optional, ``NONE``)

  Optional identifier appended to regular Bash prompt, useful for visually

  identifying distinct environments. For example, if set to ``test``, resulting

  prompt will be similar to ``admin@web[test]:~$``. Setting affects Bash shells

  *only*.

Distribution compatibility

~~~~~~~~~~~~~~~~~~~~~~~~~~

Role is compatible with the following distributions:

- Debian 10 (Buster)

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:

    "truststore": "{{ lookup('file', '../certs/truststore.pem') }}"

  incoming_connection_limit: 2/second

  incoming_connection_limit_burst: 6

  prompt_colour: light_green

  prompt_id: PROD

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

Distribution compatibility

~~~~~~~~~~~~~~~~~~~~~~~~~~

Role is compatible with the following distributions:

- Debian 10 (Buster)

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.

* Configures TLS versions and ciphers suppported by the server.

* 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 (via both

  TCP 389 and 636).

* Sets the LDAP server administrator's password.

LDIF Templates

~~~~~~~~~~~~~~

For adding users, use::

  dn: uid=USERNAME,ou=people,BASE_DN

  objectClass: inetOrgPerson

  objectClass: simpleSecurityObject

  uid: USERNAME

  userPassword: PASSWORD_FROM_SLAPPASSWD

  cn: NAME SURNAME

  sn: SURNAME

  gn: NAME

  displayName: DISPLAYNAME

  initials: INITIALS

  mail: MAIL

  mobile: MOBILE

Role dependencies

~~~~~~~~~~~~~~~~~

Depends on the following roles:

* **common**

* **ldap_client**

* **backup_client**

Backups

~~~~~~~

If the backup for this role has been enabled, the following paths are backed-up:

**/srv/backup/slapd.bak**

  Dump of the LDAP database. LDAP database dump is created every day at 01:45 in

  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 the following keys:

  **dn** (string, mandatory)

    LDAP DN entry.

  **state** (string, optional, ``present``)

    Whether the entry should be present or not. Value can be anything

    supported by the ``ldap_entry`` module. Keep in mind that state

    ``present`` will not update the attributes and their values if the

    entry is already present.

  **attributes** (dictionary, mandatory)

    Dictionary describing remaining attributes (except ``dn``). 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, 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). E.g. ``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, mandatory)

  X.509 certificate used for TLS for LDAP service. The file will be stored in

  directory ``/etc/ssl/certs/`` under name ``{{ ansible_fqdn }}_ldap.pem``.

**ldap_server_tls_key** (string, mandatory)

  Private key used for TLS for LDAP service. The file will be stored in

  directory ``/etc/ssl/private/`` under name ``{{ ansible_fqdn }}_ldap.key``.

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

  Minimum *Security Strength Factor* to require from all incoming

  connections. This applies for both remote and local connections.

**ldap_tls_ciphers** (string, optional ``NONE:+VERS-TLS1.2:+CTYPE-X509:+COMP-NULL:+SIGN-RSA-SHA256:+SIGN-RSA-SHA384:+SIGN-RSA-SHA512:+DHE-RSA:+ECDHE-RSA:+SHA256:+SHA384:+SHA512:+AEAD:+AES-128-GCM:+AES-256-GCM:+CHACHA20-POLY1305:+CURVE-ALL``)

  .. warning::

     Under Debian Buster, slapd will not use the DH parameters

     generated by the role, but will instead use them to pick one of

     the recommended DH parameters from `RFC-7919

     <https://www.ietf.org/rfc/rfc7919.txt>`_. This is based on the

     size of role-generated parameters.

  TLS ciphers to enable on the LDAP server. This should be a GnuTLS-compatible

  cipher specification that should also include what TLS protocol versions

  should be used. Value should be compatible with OpenLDAP server option

  ``olcTLSCipherSuite``. Default value allows only TLSv1.2 and strong PFS

  ciphers.

Distribution compatibility

~~~~~~~~~~~~~~~~~~~~~~~~~~

Role is compatible with the following distributions:

- Debian 10 (Buster)

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: "{{ lookup('file', '~/tls/ldap.example.com_ldap.pem') }}"

  ldap_server_tls_key: "{{ lookup('file', '~/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

      attributes:

        objectClass: organizationalUnit

        ou: people

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

      attributes:

        objectClass: organizationalUnit

        ou: groups

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

      attributes:

        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:

* Deploys XMPP TLS private key and certificate.