.. _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 11 (Bullseye)

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 11 (Bullseye)

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

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

  Python 3 is supported. Roles that want their requirements files

  checked should create a sub-directory inside of

  ``/etc/pip_check_requirements_upgrades``, 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.

---

galaxy_info:

  author: Branko Majic

  description: Generates preseed files for Debian

  license: BSD

  min_ansible_version: 2.9

  platforms:

    - name: Debian

      versions:

        - 11

---

ansible_key: MY_ANSIBLE_KEY

preseed_directory: "/tmp/preseed_files/"

preseed_server_overrides:

  parameters-optional-with-overrides-bullseye:

    country: RS

    dns: 1.1.1.1

    domain: example.com

    gateway: 2.2.2.2

    hostname: testing

    ip: 3.3.3.3

    keymap: sv

    language: sr

    locale: en_UK.UTF-8

    mirror_directory: /

    mirror_hostname: ftp.de.debian.org

    mirror_proxy: http://proxy.local

    netmask: 255.255.0.0

    network_auto: false

    network_interface: eth1

    root_password: myrootpassword

    timezone: Europe/Belgrade

---

dependency: {}

driver:

  name: vagrant

  provider:

    name: virtualbox

lint:

  name: yamllint

  options:

    config-file: ../../.yamllint.yml

platforms:

  - name: parameters-mandatory-bullseye

    groups:

      - parameters-mandatory

    box: debian/bullseye64

    memory: 256

    cpus: 1

    provider_raw_config_args:

      - "customize ['modifyvm', :id, '--paravirtprovider', 'minimal']"

  - name: parameters-optional-bullseye

    groups:

      - parameters-optional

    box: debian/bullseye64

    memory: 256

    cpus: 1

    provider_raw_config_args:

      - "customize ['modifyvm', :id, '--paravirtprovider', 'minimal']"

  - name: parameters-optional-with-overrides-bullseye

    groups:

      - parameters-optional-with-overrides

    box: debian/bullseye64

    memory: 256

    cpus: 1

    provider_raw_config_args:

      - "customize ['modifyvm', :id, '--paravirtprovider', 'minimal']"

provisioner:

  name: ansible

  config_options:

    defaults:

      force_valid_group_names: "ignore"

      interpreter_python: "/usr/bin/python3"

    ssh_connection:

      pipelining: "True"

  lint:

    name: ansible-lint

scenario:

  name: default

verifier:

  name: testinfra

  lint:

    name: flake8