Role Reference

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

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. A number of common parameters can be provided.

Parameters

~~~~~~~~~~

**preseed_directory** (mandatory)

    Destination directory where the preseed files should be stored.

**preseed_servers** (mandatory)

  List of servers for which a preseed file should be created. Each item in

  this list defines options for a single server. The options are as follows:

  **name** (string, mandatory)

    Name associated with the server. This name is used in the preseed

    configuration filename.

  **language** (string, mandatory)

    Language.

  **country** (string, mandatory)

    Country.

  **locale** (string, mandatory)

    Locale.

  **keymap** (string, mandatory)

    Keymap.

  **network_interface** (string, mandatory)

    Name of network interface (for example *eth0*) that should be

    configured.

  **network_auto** (boolean, mandatory)

    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.

  **network_ip** (string, mandatory if **network_auto** is set to ``no``)

    IP address for the server network interface.

  **network_netmask** (string, mandatory if **network_auto** is set to ``no``)

    Netmask for the server network interface.

  **network_gateway** (string, mandatory if **network_auto** is set to ``no``)

    Default gateway for the server.

  **network_dns** (string, mandatory if **network_auto** is set to ``no``)

    Comma-separated list of DNS servers.

  **network_hostname** (string, mandatory if **network_auto** is set to ``no``)

    Server hostname.

  **network_domain** (string, mandatory if **network_auto** is set to ``no``)

    Server domain.

  **mirror_hostname** (string, mandatory)

    Resolvable hostname of FQDN where the Debian apt repositories can be

    found. Only HTTP mirrors are supported.

  **mirror_directory** (string, mandatory)

    Directory under which the Debian apt repositories can be found on the

    specified mirror.

  **mirror_proxy** (string, optional, default is *None*)

    An HTTP proxy that should be used for accessing the Debian apt

    repositories.

  **root_password** (string, mandatory)

    Initial password that should be set for the server during the

    installation.

  **timezone** (string, mandatory)

    Timezone that should be used when calculating server time. It is assumed

    that the local hardware clock is set to UTC.

Examples

~~~~~~~~

Here is an example configuration for a preseed file for two servers, one with

automatic and one with manual network configuration:

.. code-block:: yaml

  ---

  preseed_directory: /var/www/preseed/

  preseed_servers:

    - name: test1.example.com

      language: en

      country: SE

      locale: en_US.UTF-8

      keymap: us

      network_interface: eth0

      network_auto: yes

      mirror_hostname: ftp.se.debian.org

      mirror_directory: /debian

      mirror_proxy: http://proxy.example.com/

      root_password: testserver

      timezone: Europe/Stockholm

    - name: test2.example.com

      language: en

      country: SE

      locale: en_US.UTF-8

      keymap: us

      network_interface: eth0

      network_auto: no

      network_ip: 10.0.0.10

      network_netmask: 255.255.255.0

      network_gateway: 10.0.0.1

      network_dns: 10.0.0.2,10.0.0.3

      network_hostname: test1

      network_domain: example.com

      mirror_hostname: ftp.se.debian.org

      mirror_proxy: http://proxy.example.com/

      mirror_directory: /debian

      root_password: testserver

      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.

Parameters

~~~~~~~~~~

**ansible_key** (string, mandatory)

  SSH public key that should be deployed to authorized_keys truststore for

  operating system user ``ansible``.

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:

* Sets-up umask for all logins to ``0027``.

* Installs sudo.

* Installs additional base packages, as configured.

* 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

  ``/etc/ssl/certs/``.

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

Parameters

~~~~~~~~~~

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

    UID for the operating system user. User's default group will have a GID

    identical to the user's UID.

  **additional_groups** (string, mandatory)

    Comma-separated list of additional groups that a user should belong to. If

    no additional groups should be appended to user's list of groups, set it to

    empty string (``""``).

  **authorized_keys** (list, mandatory)

    List of SSH public keys that should be deployed to user's authorized_keys

    truststore. If no authorized keys should be deployed, set it to empty list

    (``[]``).

  **password** (string, mandatory)

    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)

.. _testsite:

Test Site

=========

*Majic Ansible Roles* comes with a small sample test site configuration which

demonstrates use of every role. This test site also serves as starting point for

developing new roles etc, and can be used for testing regressions/breakages.

The test site covers everything, starting from generating the Debian preseed

files, through bootstrap process for new nodes, and onto deployment of all

remaining roles.

All example commands listed within this section should be ran from within the

``testsite`` directory in order to have proper environment available for

playbook runs.

A number of playbooks is provided out of the box:

bootstrap.yml (for bootstrapping fresh nodes)

  This playbook can be used for bootstrapping fresh nodes. By default, the

  entire test site will be included in the bootstrap. If you wish to limit

  bootstrap to a single server, just run the playbook with (for example):

  .. code-block:: shell

    ansible-playbook -l ldap.example.com playbooks/bootstrap.yml

ldap.yml

  This playbook sets-up the LDAP servers. It is included in ``site.yml``.

preseed.yml

  This playbook sets-up the Debian preseed files. It is included in

  ``site.yml``.

site.yml

  This playbook sets-up all servers, including preseed files on local host.

In order to deploy the test site, the following steps would normally be taken:

1. Create TLS private keys (relative to top level directory):

   - ``testsite/tls/mail.example.com_imap.key``

   - ``testsite/tls/mail.example.com_smtp.key``

   - ``testsite/tls/xmpp.example.com_xmpp.key``

   - ``testsite/tls/ldap.example.com_ldap.key``

2. Issue TLS certificates corresponding to the generated TLS private keys (make

   sure to use correct FQDN for DNS subject alternative name):

   - ``testsite/tls/mail.example.com_imap.pem`` (subject alternative name should

     be ``mail.example.com``)

   - ``testsite/tls/mail.example.com_smtp.pem`` (subject alternative name should

     be ``mail.example.com``)

   - ``testsite/tls/xmpp.example.com_xmpp.pem`` (subject alternative name should

     be ``xmpp.example.com``)

   - ``testsite/tls/ldap.example.com_ldap.pem`` (subject alternative name should

     be ``ldap.example.com``)

3. Create ``PEM`` truststore file which contains all CA certificates that form

   CA chain for the issued end entity certificates from previous step at

   location ``testsite/tls/example_ca_chain.pem``. It is very important to

   include the CA chain used for LDAP server.

4. Generate the preseed files:

  .. code-block:: shell

    ansible-playbook playbooks/preseed.yml

5. Install all servers using the generated preseed files.

   environment for Ansible runs on all servers:

  .. code-block:: shell

    ansible-playbook playbooks/bootstrap.yml

  .. code-block:: shell

    ansible-playbook playbooks/site.yml

The playbooks and configurations for test site make a couple of assumptions:

* Each server will be set-up with an operating system user ``admin``, capable of

  running the sudo commands.

* The password for operating system user ``admin`` is hard-coded to ``admin``.

* An SSH ``authorized_keys`` file is set-up for the operating system user

  ``admin``. The SSH key stored in it will be read from location

  ``~/.ssh/id_rsa.pub`` (i.e. from home directory of user running the Ansible

  commands).

For more details on how the playbooks and configuration have been implemented,

feel free to browse the test site files (in directory ``testsite``).

---

- name: Install sudo

  apt: name=sudo state=installed

- name: Set-up the Ansible group

  group: name=ansible system=yes

- name: Set-up the Ansible user

  user: name=ansible system=yes group=ansible shell=/bin/bash

- name: Set-up authorized key for the Ansible user

  authorized_key: user=ansible key="{{ ansible_key }}"

- name: Set-up password-less sudo for the ansible user