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

---

dependencies:

  - role: backup

    when: enable_backup

    backup_patterns_filename: common

    backup_patterns:

      - "/var/log"

      - "/etc/shadow"

      - "/var/mail"

      - "/var/spool/cron"

  - role: backup

    when: enable_backup

    backup_patterns_filename: common_extra

    backup_patterns: "{{ extra_backup_patterns }}"

galaxy_info:

  author: Branko Majic

  description: Apply common configuration and hardening on server

  license: BSD

  min_ansible_version: 2.9

  platforms:

    - name: Debian

      versions:

        - 10