Release notes

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

x.y.z

-----

**New features/improvements**

* ``backup_client`` role

  * Switched to using Paramiko + SFTP backend (instead of pexpect +

    SFTP), which should improve the backup performance.

**Bug fixes:**

* ``common`` role

  * Fixed permission errors with Python cache directories in the pip

  ``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 12 (Bookworm)

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** (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 12 (Bookworm)

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:

**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 12 (Bookworm)

Examples

~~~~~~~~

Here is an example configuration for setting-up some common users, groups, and

packages on all servers:

.. code-block:: yaml

  ---

  **option** (string, mandatory)

    Name of configuration option.

  **value** (string, mandatory)

    Value for configuration option.

Distribution compatibility

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

Role is compatible with the following distributions:

- Debian 12 (Bookworm)

Examples

~~~~~~~~

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

.. code-block:: yaml

  ---

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

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

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

     <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 12 (Bookworm)

Examples

~~~~~~~~

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

.. code-block:: yaml

  ---

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

**xmpp_tls_key** (string, mandatory)

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

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

Distribution compatibility

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

Role is compatible with the following distributions:

- Debian 12 (Bookworm)

Examples

~~~~~~~~

Here is an example configuration for setting-up XMPP server using Prosody:

.. code-block:: yaml

  ---

**smtp_allow_relay_from** (list, optional, [])

  List of networks from which mail relaying is allowed even without

  authentication. Each item in the list is a string defining a network. The

  format must be compatible with Postfix ``mynetworks`` setting (for example:

  ``192.168.1.0/24``, ``myhost.example.com`` etc).

Distribution compatibility

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

Role is compatible with the following distributions:

- Debian 12 (Bookworm)

Examples

~~~~~~~~

Here is an example configuration for setting-up XMPP server using Prosody:

.. code-block:: yaml

  ---

**smtp_relay_truststore** (string, mandatory)

  X.509 certificate chain used for issuing certificate for the SMTP relay

  service. The file will be stored in location

  ``/etc/ssl/certs/smtp_relay_truststore.pem``

Distribution compatibility

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

Role is compatible with the following distributions:

- Debian 12 (Bookworm)

Examples

~~~~~~~~

Here is an example configuration for setting-up the mail forwarder:

.. code-block:: yaml

  ---

**web_server_tls_ciphers** (string, optional, ``DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:DHE-RSA-CHACHA20-POLY1305:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-CHACHA20-POLY1305:!aNULL:!MD5:!EXPORT``)

  TLS ciphers to enable on the web server. This should be an OpenSSL-compatible

  cipher specification. Value should be compatible with Nginx configuration

  option ``ssl_ciphers``. Default value allows only TLSv1.2 and strong PFS

  ciphers with RSA private keys.

Distribution compatibility

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

Role is compatible with the following distributions:

- Debian 12 (Bookworm)

Examples

~~~~~~~~

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

.. code-block:: yaml

  ---

**website_mail_recipients** (string, optional, ``root``)

  Space-separated list of e-mails or local users to which the mails, sent to

  either the website admin or website user, should be forwarded to. Forwarding

  is configured via ``~/.forward`` configuration file.

Distribution compatibility

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

Role is compatible with the following distributions:

- Debian 12 (Bookworm)

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

**wsgi_requirements_in** (list, optional, ``[ gunicorn ]``)

  List of top level packages to use when performing the pip

  requirements upgrade checks for the Gunicorn requirements (listed

  via ``wsgi_requirements`` parameter).

Distribution compatibility

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

Role is compatible with the following distributions:

- Debian 12 (Bookworm)

Examples

~~~~~~~~

Here is an example configuration for setting-up a (base) WSGI website (for

running a bare Django project):

.. code-block:: yaml

    # Sample for a Django installation.

Parameters

~~~~~~~~~~

This role has no parameters.

Distribution compatibility

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

Role is compatible with the following distributions:

- Debian 12 (Bookworm)

Examples

~~~~~~~~

This role has no parameters which can be configured configure.

Database

--------

**db_name** (string, mandatory)

  Name of the database that should be created.

**db_password** (string, mandatory)

  Password for the database user.

Distribution compatibility

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

Role is compatible with the following distributions:

- Debian 12 (Bookworm)

Examples

~~~~~~~~

Here is an example configuration for creating a single database (for some

website):

.. code-block:: yaml

  - role: database

  be easily created via commands::

    ssh-keygen -f backup_server_rsa_key -N '' -t rsa

    ssh-keygen -f backup_server_ed25519_key -N '' -t ed25519

    ssh-keygen -f backup_server_ecdsa_key -N '' -t ecdsa

Distribution compatibility

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

Role is compatible with the following distributions:

- Debian 12 (Bookworm)

Examples

~~~~~~~~

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

.. code-block:: yaml

  - role: backup_server

    backup_clients:

**backup_server_port** (int, optional, ``2222``)

  Port on the backup server to connect to for accessing the SFTP service.

**backup_ssh_key** (string, mandatory)

  SSH private key for logging-in into the backup server.

Distribution compatibility

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

Role is compatible with the following distributions:

- Debian 12 (Bookworm)

Examples

~~~~~~~~

Here is an example configuration for setting-up the role (take note that lookup

plugin is quite useful here for fetching key values from some local directory):

.. code-block:: yaml

  - role: backup_client

  always unique when depending on the backup role.

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

  List of globbing patterns defining which files or directories should be

  backed-up.

Distribution compatibility

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

Role is compatible with the following distributions:

- Debian 12 (Bookworm)

Examples

~~~~~~~~

Here is an example configuration for setting-up the role:

.. code-block:: yaml

  - role: backup

    backup_patterns_filename: myapp