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. 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) 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. 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 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, mandatory) 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. 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: * 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). * Configures permissions. * Creates LDAP entries. Parameters ~~~~~~~~~~ **ldap_server_config** (list, mandatory) A dictionary of configuration options for OpenLDAP server. The following configuration options are available: **domain** (string, mandatory) Domain that should be used for constructing the base DN of default user LDAP database. This should be a sub-domain dedicated to organisation. The base DN will be constructed by putting all elements of the sub-domain as ``dc`` entries (as per standard Debian convention). I.e. ``example.com`` would get transformed into ``dc=example,dc=com``. **organization** (string, mandatory) Organization that should be specified in the base DN entry. **log_level** (string, mandatory) Log level to use for the server. This should be compatible with OpenLDAP configuration option ``olcLogLevel``. See `OpenLDAP Administrator's Guide ` for value description and syntax. **tls_certificate** (string, mandatory) Path to *X.509* certificate (on server itself) that should be used as server certificate for TLS connections. The certificate file should be provided in ``PEM`` format. If file does not exist, no TLS will be set-up. **tls_key** (string, mandatory) Path to private key (on server itself) that should be used as server's private key for TLS connections. The private key should correspond to certificate listed in option ``tls_certificate``. The key file should be provided in ``PEM`` format. If file does not exist, no TLS will be set-up. **ssf** (number, mandatory) Minimum *Security Strength Factor* to require from all incoming connections. This applies for both remote and local connections. **ldap_permissions** (list, mandatory) List of LDAP access controls to apply to directories served by the LDAP server. Each item is a dictionary with the following options describing the permissions: **filter** (string, mandatory) An LDAP filter that should be applied on base DN ``cn=config`` using sub-tree scope to locate the LDAP database for which the access control rules will be applied. For default user database this could be something in the lines of ``(olcSuffix=dc=example,dc=com)``. **rules** (list, mandatory) A list of access control rules that should be applied for the selected database. The access control rules listed will *replace* all existing rules, and will be added in the same order they are listed in. Each item is a string that constitutes a single access control rule. The format should be the same as described in `OpenLDAP Administrator's Guide `. **ldap_entries** (list, mandatory) List of entries that should be kept in the LDAP directory. Each item is a dictionary describing a single LDAP entry, with all of its attributes listed. The keys in this dictionary should be the attribute names. The values should be either strings, for setting a single attribute value, or a list of strings if it is necessary to set multiple values for the same attribute. Examples ~~~~~~~~ Here is an example configuration for setting-up LDAP server: .. code-block:: yaml --- ldap_server_config: domain: "example.com" organization: "Example Corporation" log_level: 256 tls_certificate: /etc/ssl/certs/ldap.example.com.pem tls_key: /etc/ssl/private/ldap.example.com.pem ssf: 128 ldap_permissions: - filter: '(olcSuffix=dc=example,dc=com)' rules: - > to * by dn.exact=gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth manage by * break - > to attrs=userPassword,shadowLastChange by self write by anonymous auth by dn="cn=admin,dc=example,dc=com" write by * none - > to dn.base="" by * read - > to * by self write by dn="cn=admin,dc=example,dc=com" write by users read by * none ldap_entries: - dn: ou=people,dc=example,dc=com objectClass: organizationalUnit ou: people - dn: ou=groups,dc=example,dc=com objectClass: organizationalUnit ou: groups - dn: uid=john,dc=example,dc=com objectClass: - inetOrgPerson - simpleSecurityObject userPassword: somepassword uid: john cn: John Doe sn: Doe