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.

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

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

  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_sources** (list, optional,  ``[]``)

  List of source addreses (IPv4 or IPv6) that should be allowed to

  connect to the server when in maintenance mode. Subnets can be

  specified as well.

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

  List of NTP pools 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

  pools 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

  the check itself.

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

  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.

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

.. _usage:

Usage

=====

Majic Ansible Roles are targeted at sysadmins who wish to deploy services for

their own, small-scale use. This chapter gives a simple tutorial-like set of

instructions for using all of the roles available.

.. contents:: :local:

Overview

--------

There is a number of different roles that can prove useful for setting-up a

small infrastructure of your own.

Some roles are suited for one-off operations during installation, like the

``preseed`` and ``bootstrap``, while some are better suited for periodic runs

for maintaining the users and integrity of the system.

By the end of following the instructions, you will have the following:

* Ansible server, used as controller for configuring and managing the

  remaining servers.

* Communications server, providing the LDAP, mail, and XMPP services.

* Web server, providing the web services.

* Backup server, used for storing all of the backups.

Pre-requisites

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

For the set-up outlined in this usage guide you'll need the following:

* One server where Ansible will be installed at. Debian Bookworm will

  be installed on top of this server. The server will be set-up

  manually (this is currently out of scope for the *Majic Ansible

  Roles* automated set-up).

* Three servers where the services will be set-up. All servers must be

  able to communicate over network with each-other, the Ansible

  servers, and with Internet. Debian Bookworm will be installed on top

  of these servers as part of the usage instructions.

* Debian Bookworm network installation CD.

* All servers should be on the same network.

* IP addresses for all servers should be known.

* Netmask for all servers should be known.

* Gateway for all servers should be known.

In case of the servers listed above, it might be safest to have them

as virtual machines - this is cheapest thing to do, and simplest (who

wants to deal with pesky hardware anyway?).

Usage instructions assume the following:

* Domain used for all servers is ``example.com``. If you wish to use a different

  domain, adjust the instructions accordingly.

* Server hostnames are ``ansible``, ``comms``, ``www``, and ``bak`` (for Ansible

  server, communications server, web server, and backup server, respectively).

Installing the OS on Ansible server

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

Start-off by installing the operating system on the Ansible server:

1. Fire-up the ``ansible`` server, and boot from the network installation CD.

2. Select the **Install** option.

3. Pick **English** as language.

4. Pick the country you are living in (or whatever else you want).

5. Pick the **en_US.UTF-8** locale.

6. Pick the **American English** keymap.