Changeset - a25135cc9e78
[Not reviewed]
1 1 0
Branko Majic (branko) - 9 years ago 2015-08-28 19:12:52
branko@majic.rs
MAR-19: Updated documentation for the preseed role to match parameter redesign. Removed some testing file that was added to playbooks by mistake earlier.
2 files changed with 90 insertions and 93 deletions:
0 comments (0 inline, 0 general)
docs/rolereference.rst
Show inline comments
 
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.
 
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)
 
**ansible_key** (string, optional, ``{{ lookup('file', '~/.ssh/id_rsa.pub') }}``)
 
  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 Jessie does not allow password-based logins for root.
 

	
 
**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.
 
**preseed_country** (string, optional, ``SE``)
 
  Country.
 

	
 
  **language** (string, mandatory)
 
    Language.
 
**preseed_directory** (string, optional, ``../preseed_files/``)
 
  Destination directory where the preseed files should be stored.
 

	
 
  **country** (string, mandatory)
 
    Country.
 
  .. 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).
 

	
 
  **locale** (string, mandatory)
 
    Locale.
 
**preseed_dns** (string, mandatory if **preseed_network_auto** is ``no``)
 
  Comma-separated list of DNS servers.
 

	
 
  **keymap** (string, mandatory)
 
    Keymap.
 
**preseed_domain** (string, mandatory if **preseed_network_auto** is ``no``)
 
  Server domain.
 

	
 
  **network_interface** (string, mandatory)
 
    Name of network interface (for example *eth0*) that should be
 
    configured.
 
**preseed_gateway** (string, mandatory if **preseed_network_auto** is ``no``)
 
  Default gateway for the server.
 

	
 
  **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.
 
**preseed_hostname** (string, mandatory if **preseed_network_auto** is ``no``)
 
  Server hostname.
 

	
 
  **network_ip** (string, mandatory if **network_auto** is set to ``no``)
 
**preseed_ip** (string, mandatory if **preseed_network_auto** is ``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.
 
**preseed_keymap** (string, optional, ``us``)
 
  Keymap.
 

	
 
  **network_dns** (string, mandatory if **network_auto** is set to ``no``)
 
    Comma-separated list of DNS servers.
 
**preseed_language** (string, optional, ``en``)
 
  Language.
 

	
 
  **network_hostname** (string, mandatory if **network_auto** is set to ``no``)
 
    Server hostname.
 
**preseed_locale** (string, optional, ``en_US.UTF-8``)
 
  Locale.
 

	
 
  **network_domain** (string, mandatory if **network_auto** is set to ``no``)
 
    Server domain.
 
**preseed_mirror_directory** (string, optional, ``/debian``)
 
  Directory under which the Debian apt repositories can be found on the
 
  specified mirror.
 

	
 
  **mirror_hostname** (string, mandatory)
 
**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.
 

	
 
  **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*)
 
**preseed_mirror_proxy** (string, optional, ``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.
 
**preseed_netmask** (string, mandatory if **preseed_network_auto** is ``no``)
 
  Netmask for the server network interface.
 

	
 
  **timezone** (string, mandatory)
 
    Timezone that should be used when calculating server time. It is assumed
 
    that the local hardware clock is set to UTC.
 
**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.
 

	
 

	
 
Examples
 
~~~~~~~~
 

	
 
Here is an example configuration for a preseed file for two servers, one with
 
automatic and one with manual network configuration:
 
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
 

	
 
  ---
 

	
 
  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
 
  ansible_key: /root/ansible/private.key
 
  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
 
      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
 
      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``.
 

	
 

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

	
 
**apt_proxy** (string, optional)
 
  URI of a caching proxy that should be used when retrieving the packages via
 
  apt. Default is no proxy.
 

	
 
**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)
 
    Name of the operating system group that should be created.
 

	
 
  **gid** (number, mandatory)
 
    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)
 
  List of additional CA certificate files that should be deployed on the
 
  server. Each element of the list should be a filepath to a CA certificate file
 
  on originating (Ansible) host that should be copied to destination
 
  server.
 

	
 
**incoming_connection_limit** (string, mandatory)
 
  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, mandatory)
 
  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.
 

	
 

	
 
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
 
      additional_groups: ""
 
      authorized_keys: []
 
      password: '$6$AaJRWtqyX5pk$IP8DUjgY0y2zqMom9BAc.O9qHoQWLFCmEsPRCika6l/Xh87cp2SnlMywH0.r4uEcbHnoicQG46V9VrJ8fxp2d.'
 

	
 
  os_groups:
 
    - name: localusers
 
      gid: 2500
 

	
 
  common_packages:
 
    - emacs23-nox
 
    - screen
 
    - debconf-utils
 

	
 
  ca_certificates:
 
    - ../certs/truststore.pem
 

	
 
  incoming_connection_limit: 2/second
 

	
 
  incoming_connection_limit_burst: 6
 

	
 
.. _ldap_client:
 

	
 
LDAP Client
testsite/playbooks/testing.yml
Show inline comments
 
deleted file
0 comments (0 inline, 0 general)