.. _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) - Debian 12 (Bookworm) 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 `_ 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. Parameters ~~~~~~~~~~ **apt_proxy** (string, optional, ``None``) URI of a caching proxy that should be used when retrieving the packages via apt. **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, optional, ``whatever OS picks``) UID for the operating system user. User's default group will have a GID identical to the user's UID if specified. Otherwise user's default group will have OS-determined GID. **additional_groups** (list, optional, ``[]``) List of additional groups that a user should belong to. **authorized_keys** (list, optional, ``[]``) List of SSH public keys that should be deployed to user's authorized_keys truststore. **password** (string, optional, ``!`` - no password) 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, optional, ``whatever OS picks``) 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, ``{}``) 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 package upgrades for the Python 3 virtual environment used to run the check itself. **pip_check_requirements** (list, optional, ``see below``) List of Python package requirements to install in Python 3 virtual 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*. Distribution compatibility ~~~~~~~~~~~~~~~~~~~~~~~~~~ Role is compatible with the following distributions: - Debian 11 (Bullseye) - Debian 12 (Bookworm) 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 password: '$6$AaJRWtqyX5pk$IP8DUjgY0y2zqMom9BAc.O9qHoQWLFCmEsPRCika6l/Xh87cp2SnlMywH0.r4uEcbHnoicQG46V9VrJ8fxp2d.' os_groups: - name: localusers gid: 2500 common_packages: - emacs23-nox - screen - debconf-utils ca_certificates: "truststore": "{{ lookup('file', '../certs/truststore.pem') }}" incoming_connection_limit: 2/second incoming_connection_limit_burst: 6 prompt_colour: light_green prompt_id: PROD .. _ldap_client: 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, optional, ``[]``) 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. Distribution compatibility ~~~~~~~~~~~~~~~~~~~~~~~~~~ Role is compatible with the following distributions: - Debian 11 (Bullseye) - Debian 12 (Bookworm) 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: * Deploys LDAP TLS private key and certificate. * Configures TLS versions and ciphers suppported by the server. * 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), but *only* on Debian 11 Bullseye. Starting with Debian 12 Bookworm, the use of rsyslog is considered to be deprecated by Majic Ansible Roles. * Enables the ``misc`` LDAP schema (from ``/etc/ldap/schema/misc.ldif``). This is necessary for the mail server role. * Enables the ``memberof`` overlay on top of default database. The overlay is configured to keep track of membership changes for object class ``groupOfUniqueNames`` via attribute ``uniqueMember``. Enforcement of referential integrity is turned on as well (modifications of ``memberof`` attribute will update corresponding group as well. * Creates a basic directory structure used by most of the other roles. * Creates a basic directory structure used by the mail server role. * Creates login entries for services that need to consume LDAP directory data in some way. * Creates user-supplied groups in LDAP. * Configures permissions. * Creates LDAP entries. * Configures firewall to allow incoming connections to the LDAP server (via both TCP 389 and 636). * Sets the LDAP server administrator's password. LDIF Templates ~~~~~~~~~~~~~~ For adding users, use:: dn: uid=USERNAME,ou=people,BASE_DN objectClass: inetOrgPerson objectClass: simpleSecurityObject uid: USERNAME userPassword: PASSWORD_FROM_SLAPPASSWD cn: NAME SURNAME sn: SURNAME gn: NAME displayName: DISPLAYNAME initials: INITIALS mail: MAIL mobile: MOBILE Role dependencies ~~~~~~~~~~~~~~~~~ Depends on the following roles: * **common** * **ldap_client** * **backup_client** Backups ~~~~~~~ If the backup for this role has been enabled, the following paths are backed-up: **/srv/backup/slapd.bak** Dump of the LDAP database. LDAP database dump is created every day at 01:45 in the morning. This does *not* include the dump of the config database (``cn=config``). Parameters ~~~~~~~~~~ **ldap_admin_password** (string, mandatory) Password for the default administrator account of LDAP server (the ``cn=admin,DOMAIN`` entry/user). **ldap_entries** (list, optional, ``[]``) List of entries that should be kept in the LDAP directory. Each item is a dictionary describing a single LDAP entry with the following keys: **dn** (string, mandatory) LDAP DN entry. **state** (string, optional, ``present``) Whether the entry should be present or not. Value can be anything supported by the ``ldap_entry`` module. Keep in mind that state ``present`` will not update the attributes and their values if the entry is already present. **attributes** (dictionary, mandatory) Dictionary describing remaining attributes (except ``dn``). 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. **ldap_permissions** (list, optional, ``see below``) List of LDAP access rules to apply to base DN served by the LDAP server. The listed access control rules 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 `. Default value is: .. code-block:: yaml - > 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,BASEDN" write by * none - > to dn.base="" by * read - > to * by self write by dn="cn=admin,BASEDN" write by * none **ldap_server_consumers** (list, optional, ``[]``) List of items describing additional login entries that should be created for services that want to be able to log-in into the LDAP server and consume the data present within. Each item should be a dictionary, with the following keys avaialable: - **name** (name of the service, mandatory, this will be used to construct the login entry DN in format of ``cn=NAME,ou=services,BASE_DN``) - **password** (password for the login entry, mandatory) - **state** (state of the service, optional, defaults to ``present``, this should be ``present`` or ``absent``, allowing for removal of old services) **ldap_server_groups** (list, optional, ``[]``) List of groups that should be created in the LDAP directory. Each item should be a dictionary containing the following keys: - **name** (name of the group, mandatory, this will be used to construct the group DN in format of ``cn=NAME,ou=groups,BASE_DN``) - **state** (state of the group, optional, defaults to ``present``, this should be ``present`` or ``absent``, allowing for removal of old groups) **ldap_server_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). E.g. ``example.com`` would get transformed into ``dc=example,dc=com``. **ldap_server_organization** (string, optional, ``Private``) Organization that should be specified in the base DN entry. **ldap_server_log_level** (string, optional, ``256``) 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. **ldap_server_tls_certificate** (string, mandatory) X.509 certificate used for TLS for LDAP service. The file will be stored in directory ``/etc/ssl/certs/`` under name ``{{ ansible_fqdn }}_ldap.pem``. **ldap_server_tls_key** (string, mandatory) Private key used for TLS for LDAP service. The file will be stored in directory ``/etc/ssl/private/`` under name ``{{ ansible_fqdn }}_ldap.key``. **ldap_server_ssf** (number, optional, ``128``) Minimum *Security Strength Factor* to require from all incoming connections. This applies for both remote and local connections. **ldap_tls_ciphers** (string, optional ``NONE:+VERS-TLS1.2:+CTYPE-X509:+COMP-NULL:+SIGN-RSA-SHA256:+SIGN-RSA-SHA384:+SIGN-RSA-SHA512:+DHE-RSA:+ECDHE-RSA:+SHA256:+SHA384:+SHA512:+AEAD:+AES-128-GCM:+AES-256-GCM:+CHACHA20-POLY1305:+CURVE-ALL``) .. warning:: Under Debian Bullseye and upwards, slapd will not use the DH parameters generated by the role, but will instead use them to pick one of the recommended DH parameters from `RFC-7919 `_. This is based on the size of role-generated parameters. TLS ciphers to enable on the LDAP server. This should be a GnuTLS-compatible cipher specification that should also include what TLS protocol versions should be used. Value should be compatible with OpenLDAP server option ``olcTLSCipherSuite``. Default value allows only TLSv1.2 and strong PFS ciphers. Distribution compatibility ~~~~~~~~~~~~~~~~~~~~~~~~~~ Role is compatible with the following distributions: - Debian 11 (Bullseye) - Debian 12 (Bookworm) Examples ~~~~~~~~ Here is an example configuration for setting-up LDAP server: .. code-block:: yaml --- ldap_server_domain: "example.com" ldap_server_organization: "Example Corporation" ldap_server_log_level: 256 ldap_server_tls_certificate: "{{ lookup('file', '~/tls/ldap.example.com_ldap.pem') }}" ldap_server_tls_key: "{{ lookup('file', '~/tls/ldap.example.com_ldap.key') }}" ldap_server_ssf: 128 ldap_permissions: - > 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 attributes: objectClass: organizationalUnit ou: people - dn: ou=groups,dc=example,dc=com attributes: objectClass: organizationalUnit ou: groups - dn: uid=john,dc=example,dc=com attributes: objectClass: - inetOrgPerson - simpleSecurityObject userPassword: somepassword uid: john cn: John Doe sn: Doe XMPP Server ----------- The ``xmpp_server`` role can be used for setting-up Prosody, an XMPP server, on destination machine. The role implements the following: * Deploys XMPP TLS private key and certificate. .. warning:: The issued certificate must have multiple FQDNs listed as subject alternative names (DNS names) for each configured domain: - domain itself - ``conference.DOMAIN`` - ``proxy.DOMAIN`` A daily cron job is run to validate that all certificates have been configured and issued correctly. * Installs Prosody. * Configures Prosody. * Configures firewall to allow incoming connections to the XMPP server. Prosody is configured as follows: * Modules enabled: roster, saslauth, tls, dialback, posix, private, vcard, version, uptime, time, ping, pep, register, admin_adhoc, announce, legacyauth, carbons, mam. * Self-registration is not allowed. * TLS is configured. Legacy TLS is available on port 5223. * Client-to-server communication requires encryption (TLS). * Uses 2048-bit Diffie-Hellman parameters for relevant TLS ciphers for incoming connections. * Configures TLS versions and ciphers supported by Prosody (for *c2s*/client connections only). * Authentication is done via LDAP. For setting the LDAP TLS truststore, see :ref:`LDAP Client `. * Internal storage is used. * For each domain specified, a dedicated conference/multi-user chat (MUC) service is set-up, with FQDN set to ``conference.DOMAIN``. * For each domain specified, a dedicated file proxy service will be set-up, with FQDN set to ``proxy.DOMAIN``. Prosody expects a specific directory structure in LDAP when doing look-ups: * Prosody will log-in to LDAP as user ``cn=prosody,ou=services,XMPP_LDAP_BASE_DN``. * User entries are read from sub-tree (first-level only) ``ou=people,XMPP_LDAP_BASE_DN``. Query filter used for finding users is ``(&(mail=$user@$host)(memberOf=cn=xmpp,ou=groups,XMPP_LDAP_BASE_DN))``. This allows group-based granting of XMPP service to users. LDIF Templates ~~~~~~~~~~~~~~ For adding user to a group, use:: dn: cn=xmpp,ou=groups,BASE_DN changetype: modify add: uniqueMember uniqueMember: uid=USERNAME,ou=people,BASE_DN Role dependencies ~~~~~~~~~~~~~~~~~ Depends on the following roles: * **common** * **backup_client** Backups ~~~~~~~ If the backup for this role has been enabled, the following paths are backed-up: **/var/lib/prosody/** Roster information, as well as undelivered (offline) messages for all XMPP users. Keep in mind that list of available users and their credentials are stored in the LDAP directory (which is backed-up via LDAP server role). Parameters ~~~~~~~~~~ **xmpp_administrators** (list, mandatory) List of Prosody users that should be granted administrator privileges over Prosody. Each item is a string with value equal to XMPP user ID (i.e. ``john.doe@example.com``). **xmpp_domains** (list, mandatory) List of domains that are served by this Prosody instance. Each item is a string specifying a domain. **xmpp_ldap_base_dn** (string, mandatory) Base DN on the LDAP server. A specific directory structure is expected under this entry (as explained above) in order to locate the available domains, users, aliases etc. **xmpp_ldap_password** (string, mandatory) Password used for authenticating to the LDAP server. **xmpp_ldap_server** (string, mandatory) Fully qualified domain name, hostname, or IP address of the LDAP server used for user authentication and listing. **xmpp_server_archive_expiration** (string, optional, ``never``) Expiration period for messages stored server-side using `XEP-0313: Message Archive Management `_. The value should be compatible with `Prosody mod_mam `_ configuration option ``archive_expires_after``. **xmpp_server_tls_ciphers** (string, optional ``DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:DHE-RSA-CHACHA20-POLY1305:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-CHACHA20-POLY1305:!aNULL:!MD5:!EXPORT``) TLS ciphers to enable on the XMPP server. This should be an OpenSSL-compatible cipher specification. Value should be compatible with Prosody's option ``ciphers`` normally defined within the ``ssl`` section of configuration file (see `official documentation `_ for details). Default value allows only TLSv1.2 and strong PFS ciphers with RSA private keys. **xmpp_server_tls_protocol** (string, optional, ``tlsv1_2+``) Protocol version the XMPP server should support for client connections. The value specified should be compatible with Prosody's ``protocol`` option normally defined within the ``ssl`` section of configuration file (see `official documentation `__ for details). **xmpp_tls_certificate** (string, mandatory) X.509 certificate used for TLS for XMPP service. The file will be stored in directory ``/etc/ssl/certs/`` under name ``{{ ansible_fqdn }}_xmpp.pem``. **xmpp_tls_key** (string, mandatory) Private key used for TLS for XMPP service. The file will be stored in directory ``/etc/ssl/private/`` under name ``{{ ansible_fqdn }}_xmpp.key``. Distribution compatibility ~~~~~~~~~~~~~~~~~~~~~~~~~~ Role is compatible with the following distributions: - Debian 11 (Bullseye) - Debian 12 (Bookworm) Examples ~~~~~~~~ Here is an example configuration for setting-up XMPP server using Prosody: .. code-block:: yaml --- xmpp_administrators: - john.doe@example.com xmpp_domains: - example.com xmpp_ldap_base_dn: dc=example,dc=com xmpp_ldap_password: xmpp xmpp_ldap_server: ldap.example.com # These are default key and certificate that generated during Prosody # installation. Possibly you want to deploy your own. xmpp_tls_key: "{{ lookup('file', '/etc/prosody/certs/localhost.key') }}" xmpp_tls_certificate: "{{ lookup('file', '/etc/prosody/certs/localhost.crt') }}" Mail Server ----------- .. warning:: It may happen that the ``clamav-freshclam`` service hasn't finished downloading the virus database before the ``clamav-daemon`` and ``clamav-milter`` services are enabled during the initial run. If mail server is not operational, you may need to wait for a little while for download to finish, and then restart the ``clamav-daemon`` and ``clamav-milter`` services. The ``mail_server`` role can be used for setting-up a complete mail server solution, which includes both SMTP and IMAP service, on destination machine. Postfix is used SMTP, while Dovecot is used for IMAP. The role implements the following: * Installs rsync. * Deploys IMAP/SMTP TLS private keys and certificates. * Installs and configures Dovecot, Postfix, ClamAV, and ClamAV Milter. * Purges Exim4 configuration (just in case). * Sets-up aliases for the local recipients. * Installs SWAKS (utility for testing SMTP servers). * Sets-up the necessary directories and files under Postfix chroot. * Configures firewall to allow incoming connections to the mail server. This includes set-up of redirection from TCP port 26 to TCP port 587 (alternate submission port), as well as redirection from TCP port 27 to TCP port 25 (alternate SMTP port), useful as workaround for ISP/hotel blocks. Deployed services are configured as follows: * Both Postfix and Dovecot look-up available domains, users, and aliases in LDAP. * Incoming and outgoing mail is scanned with ClamAV (via ClamAV Milter). Infected mails are rejected. * Mail is stored in directory ``/var/MAIL_USER/DOMAIN/USER``, using ``Maildir`` format. * TLS is required for user log-ins for both SMTP and IMAP. * Uses 2048-bit Diffie-Hellman parameters for relevant TLS ciphers for incoming connections. * For user submission (SMTP), users must connect and authenticate over TCP port 587. * Configures TLS versions and ciphers supported by Dovecot. * Configures TLS versions and ciphers supported by Postfix on submission port (587). TLS configuration on port 25 is kept intact in order to maintain maximum interoperability with other servers. * RBL's are used for combating spam (if any is specified in configuration, see below). * Postfix is configured to deliver undeliverable bounces to postmaster. This helps with detecting misconfigured applications and servers. * Postfix is configured to prevent forging of sender addresses for logged-in users. Logged-in users can use either their own e-mail as sender, or one of the aliases associated with their e-mail. Both Postfix and Dovecot expect a specific directory structure in LDAP when doing look-ups: * Postfix will log-in to LDAP as user ``cn=postfix,ou=services,MAIL_LDAP_BASE_DN``. * Dovecot will log-in to LDAP as user ``cn=dovecot,ou=services,MAIL_LDAP_BASE_DN``. * Domain entries need to be available as ``dc=DOMAIN,ou=domains,ou=mail,ou=services,MAIL_LDAP_BASE_DN``. * Alias entries need to be available as ``cn=ALIAS,ou=aliases,ou=mail,ou=services,MAIL_LDAP_BASE_DN``. * User entries are read from sub-tree (first-level only) ``ou=people,MAIL_LDAP_BASE_DN``. Query filter used for finding users is ``(&(mail=%s)(memberOf=cn=mail,ou=groups,MAIL_LDAP_BASE_DN))``. This allows group-based granting of mail services to users. LDIF Templates ~~~~~~~~~~~~~~ For adding domains, use:: dn: dc=DOMAIN,ou=domains,ou=mail,ou=services,BASE_DN objectClass: dNSDomain dc: DOMAIN For adding aliases, use:: dn: cn=ALIAS,ou=aliases,ou=mail,ou=services,BASE_DN objectClass: nisMailAlias cn: ALIAS rfc822MailMember: REALEMAIL For adding user to a group, use:: dn: cn=mail,ou=groups,BASE_DN changetype: modify add: uniqueMember uniqueMember: uid=USERNAME,ou=people,BASE_DN Role dependencies ~~~~~~~~~~~~~~~~~ Depends on the following roles: * **common** * **backup_client** Backups ~~~~~~~ If the backup for this role has been enabled, the following paths are backed-up: **/var/{{ mail_user }}** All data stored by the mail server, including mails and Sieve scripts. Keep in mind that list of available users and their credentials are stored in the LDAP directory (which is backed-up via LDAP server role). Parameters ~~~~~~~~~~ **mail_ldap_base_dn** (string, mandatory) Base DN on the LDAP server. A specific directory structure is expected under this entry (as explained above) in order to locate the available domains, users, aliases etc. **mail_ldap_url** (string, mandatory) LDAP URL that should be used for connecting to the LDAP server for doing domain/user look-ups. **mail_ldap_tls_truststore** (string, mandatory) X.509 certificate chain used for issuing certificate for the LDAP service. The file will be stored in locations ``/etc/ssl/certs/mail_ldap_tls_truststore.pem`` and ``/var/spool/postfix/etc/ssl/certs/mail_ldap_tls_truststore.pem``. **mail_ldap_postfix_password** (string, mandatory) Password for authenticating the Postfix LDAP user. **mail_ldap_dovecot_password** (string, mandatory) Password for authenticating the Dovecot LDAP user. **mail_message_size_limit** (integer, optional, ``10240000``) Maximum size of message in bytes that the SMTP server should accept for incoming mails. If the mail message size exceeds the listed value, it will be rejected by the server. The size is also advertised as part of SMTP server capabilities (in response to the ``ehlo`` SMTP command). **mail_server_minimum_tls_protocol** (string, optional, ``"TLSv1.2"``) Minimum version of TLS protocol to allow when connecting to SMTP submission port or IMAP. Value should be compatible with Dovecot's ``ssl_protocols`` configuration option. **mail_server_smtp_additional_configuration** (string, optional, ``""``)) Additional configuration directives to include in SMTP server main configuration file. Directives must be specifically compatible with Postfix, and are treated verbatim (multi-line string will suffice). **mail_server_tls_ciphers** (string, optional ``DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:DHE-RSA-CHACHA20-POLY1305:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-CHACHA20-POLY1305:!aNULL:!MD5:!EXPORT``) TLS ciphers to enable on the mail server (for IMAP and SMTP submission). This should be an OpenSSL-compatible cipher specification. Value should be compatible with Postfix configuration option ``tls_high_cipherlist`` and Dovecot configuration option ``ssl_cipher_list``. Default value allows only TLSv1.2 and strong PFS ciphers. **mail_user** (string, optional, ``vmail``) Name of the user that owns all the mail files. **mail_user_uid** (integer, optional, ``whatever OS picks``) UID of the user that owns all the mail files. **mail_user_gid** (integer, optional, ``whatever OS picks``) GID of the user that owns all the mail files. **imap_max_user_connections_per_ip** (integer, optional, ``10``) Maximum number of IMAP connections from a single IP for a single user. Default value can be considered rather low, since two devices (computer and phone) will easily reach it. **imap_tls_certificate** (string, mandatory) X.509 certificate used for TLS for IMAP service. The file will be stored in directory ``/etc/ssl/certs/`` under name ``{{ ansible_fqdn }}_imap.pem``. **imap_tls_key** (string, mandatory) Private key used for TLS for IMAP service. The file will be stored in directory ``/etc/ssl/private/`` under name ``{{ ansible_fqdn }}_imap.key``. **local_mail_aliases** (dictionary, optional, ``{}``) Dictionary defining the local aliases. Aliases defined this way will either be appended to default aliases on the server, or replace the existing entries (if the alias/recipient is already present). Keys in the dictionary are the local recipients/aliases, while the value provided should be a space-separated list of mail addresses (or local users) where the mails should be forwarded. **smtp_tls_certificate** (string, mandatory) X.509 certificate used for TLS for SMTP service. The file will be stored in directory ``/etc/ssl/certs/`` under name ``{{ ansible_fqdn }}_smtp.pem``. **smtp_tls_key** (string, mandatory) Private key used for TLS for SMTP service. The file will be stored in directory ``/etc/ssl/private/`` under name ``{{ ansible_fqdn }}_smtp.key``. **imap_folder_separator** (string, optional, ``/``) Character used for separating the IMAP folders when clients are requesting listing from the server. Usually either slash(``/``) or dot(``.``). **smtp_rbl** (list, optional, ``[]``) List of RBLs to use for detecting servers which send out spam. Each item is a string resembling the RBL domain. **mail_postmaster** (string, optional, ``postmaster@{{ ansible_domain}}``) Mail address to use for the postmaster account in Dovecot. **smtp_allow_relay_from** (list, optional, []) List of networks from which mail relaying is allowed even without authentication. Each item in the list is a string defining a network. The format must be compatible with Postfix ``mynetworks`` setting (for example: ``192.168.1.0/24``, ``myhost.example.com`` etc). Distribution compatibility ~~~~~~~~~~~~~~~~~~~~~~~~~~ Role is compatible with the following distributions: - Debian 11 (Bullseye) - Debian 12 (Bookworm) Examples ~~~~~~~~ Here is an example configuration for setting-up XMPP server using Prosody: .. code-block:: yaml --- mail_ldap_url: ldap://ldap.example.com/ mail_ldap_tls_truststore: /etc/ssl/certs/truststore.pem mail_ldap_base_dn: dc=example,dc=com mail_ldap_postfix_password: postfix mail_ldap_dovecot_password: dovecot mail_user: vmail mail_user_uid: 5000 mail_user_gid: 5000 # All mails sent to local user root will be forwarded to external account as # well. local_mail_aliases: root: "root john.doe@example.com" imap_tls_certificate: "{{ lookup('file', '~/tls/mail.example.com_imap.pem') }}" imap_tls_key: "{{ lookup('file', '~/tls/mail.example.com_imap.key') }}" smtp_tls_certificate: "{{ lookup('file', '~/tls/mail.example.com_smtp.pem') }}" smtp_tls_key: "{{ lookup('file', '~/tls/mail.example.com_smtp.key') }}" imap_folder_separator: / smtp_rbl: - bl.spamcop.net - zen.spamhaus.org mail_postmaster: postmaster@example.com smtp_allow_relay_from: - ldap.example.com - xmpp.example.com imap_max_user_connections_per_ip: 50 Mail Forwarder -------------- The ``mail_forwarder`` role can be used for setting-up a local SMTP server for sending out mails and receiving mails for local users. The SMTP server is provided by Postfix. SMTP service on server set-up this way is not meant to be exposed to the Internet directly, and should receive delivery failures from the relay server instead. The role implements the following: * Installs and configures Postfix. * Purges Exim4 configuration (just in case). * Sets-up aliases for the local recipients. * Installs SWAKS (utility for testing SMTP servers). * Configures firewall to accept SMTP connections from SMTP relay (if one has been configured). This allows for delivery of bounced e-mails. .. note:: Firewall rules are based on IPv4 and IPv6 addresses resolved via managed server at time of deployment. If the SMTP relay changes its IP addresess, this role needs to be reapplied against the managed machines. Postfix is configured as follows: * Local destinations are set-up. * A relay host is set. * TLS is enforced for relaying mails, with configurable truststore for server certificate verification if SMTP relay is used. If SMTP relay is not used (configured), no certificate verification is done. * Uses 2048-bit Diffie-Hellman parameters for relevant TLS ciphers for incoming connections. Role dependencies ~~~~~~~~~~~~~~~~~ Depends on the following roles: * **common** Parameters ~~~~~~~~~~ **local_mail_aliases** (dictionary, optional, ``[]``) Dictionary defining the local aliases. Aliases defined this way will either be appended to default aliases on the server, or replace the existing entries (if the alias/recipient is already present). Keys in the dictionary are the local recipients/aliases, while the value provided should be a space-separated list of mail addresses (or local users) where the mails should be forwarded. **mail_message_size_limit** (integer, optional, ``10240000``) Maximum size of message in bytes that the SMTP server should accept for incoming mails. If the mail message size exceeds the listed value, it will be rejected by the server. The size is also advertised as part of SMTP server capabilities (in response to the ``ehlo`` SMTP command). Changing the value is primarily useful when SMTP from relay is allowed (via the ``smtp_from_relay_allowed`` parameter), since incoming SMTP communication is otherwise not allowed at all. **smtp_from_relay_allowed** (boolean, optional, ``True``) Specify if SMTP traffic from SMTP relay should be allowed or not (for bounced messages, for example). This parameter should be set to ``False`` on systems behind NAT or on systems that may not have constant network connectivity (such as laptops) to avoid firewall failures since SMTP relay name needs to be resolvable. **smtp_relay_host** (string, optional, ``None``) SMTP server via which the mails are sent out for non-local recipients. **smtp_relay_host_port** (integer, optional, ``None``) Port to use when connecting to the SMTP relay host. **smtp_relay_truststore** (string, mandatory) X.509 certificate chain used for issuing certificate for the SMTP relay service. The file will be stored in location ``/etc/ssl/certs/smtp_relay_truststore.pem`` Distribution compatibility ~~~~~~~~~~~~~~~~~~~~~~~~~~ Role is compatible with the following distributions: - Debian 11 (Bullseye) - Debian 12 (Bookworm) Examples ~~~~~~~~ Here is an example configuration for setting-up the mail forwarder: .. code-block:: yaml --- # All mails sent to local user root will be forwarded to external account as # well. local_mail_aliases: root: "root john.doe@example.com" smtp_relay_host: mail.example.com smtp_relay_host_port: 27 smtp_from_relay_allowed: False smtp_relay_truststore: /etc/ssl/certs/example_ca_chain.pem Web Server ---------- The ``web_server`` role can be used for setting-up a web server on destination machine. The role is supposed to be very lightweight, providing a basis for deployment of web applications. The role implements the following: * Installs and configures nginx with a single, default vhost with a small static index page. * Deploys the HTTPS TLS private key and certificate (for default vhost). * Configures TLS versions and ciphers supported by Nginx. * Uses 2048-bit Diffie-Hellman parameters for relevant TLS ciphers for incoming connections. * Configures firewall to allow incoming connections to the web server. * Installs and configures virtualenv and virtualenvwrapper as a common base for Python apps. * Installs and configures PHP FPM as a common base for PHP apps. The web server is configured as follows: * No plaintext HTTP is allowed, HTTPS is mandatory. Clients connecting via plaintext HTTP are redirected to HTTPS. * Clients are served with ``Strict-Transport-Security`` header with value of ``max-age=31536000; includeSubDomains``. This forces compliant clients to always connect using HTTPS to the web server when accessing its default domain, as well as any subdomains served by this web server or any other. The (client-side) cached header value expires after one year. Role dependencies ~~~~~~~~~~~~~~~~~ Depends on the following roles: * **common** Parameters ~~~~~~~~~~ **default_https_tls_certificate** (string, mandatory) X.509 certificate used for TLS for HTTPS service. The file will be stored in directory ``/etc/ssl/certs/`` under name ``{{ ansible_fqdn }}_https.pem``. **default_https_tls_key** (string, mandatory) Private key used for TLS for HTTPS service. The file will be stored in directory ``/etc/ssl/private/`` under name ``{{ ansible_fqdn }}_https.key``. **environment_indicator** (dictionary, optional, ``null``) Specify configuration for including environment indicator on all HTML pages. Indicator is a simple strip at bottom of a page with custom background colour, text colour, and text. Indicator can be collapsed by clicking on the arrows on the left side of the strip. Specifying environment indicator is useful for avoiding mistakes when testing by having better visibility what environment you are in (production/staging/test). The following keys need to be specified: **background_colour** (string, mandatory) Background colour to use for the strip at bottom. This should be value compatible with CSS ``background-color`` attribute. **text_colour** (string, mandatory) Text colour to use for the strip at bottom. This should be value compatible with CSS ``color`` attribute. **text** (string, mandatory) Text to show in show in the strip at bottom. **web_default_title** (string, optional, ``Welcome``) Title for the default web page shown to users (if no other vhosts were matched). **web_default_message** (string, optional, ``You are attempting to access the web server using a wrong name or an IP address. Please check your URL.``) Message for the default web page shown to users (if no other vhosts were matched). **web_server_tls_protocols** (list, optional, ``[ "TLSv1.2" ]``) List of TLS protocols the web server should support. Each value specified should be compatible with Nginx configuration option ``ssl_protocols``. **web_server_tls_ciphers** (string, optional, ``DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:DHE-RSA-CHACHA20-POLY1305:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-CHACHA20-POLY1305:!aNULL:!MD5:!EXPORT``) TLS ciphers to enable on the web server. This should be an OpenSSL-compatible cipher specification. Value should be compatible with Nginx configuration option ``ssl_ciphers``. Default value allows only TLSv1.2 and strong PFS ciphers with RSA private keys. Distribution compatibility ~~~~~~~~~~~~~~~~~~~~~~~~~~ Role is compatible with the following distributions: - Debian 11 (Bullseye) - Debian 12 (Bookworm) Examples ~~~~~~~~ Here is an example configuration for setting-up web server: .. code-block:: yaml --- default_https_tls_key: "{{ lookup('file', inventory_dir + '/tls/web.example.com_https.key') }}" default_https_tls_certificate: "{{ lookup('file', inventory_dir + '/tls/web.example.com_https.pem') }}" web_default_title: "Welcome to Example Inc." web_default_message: "You are attempting to access the web server using a wrong name or an IP address. Please check your URL." PHP Website ----------- The ``php_website`` role can be used for setting-up a website powered by PHP on destination machine. This role is normally not supposed to be used directly, but should instead serve as the basis for writing website-specific roles. Therefore the role is written in quite generic way, allowing the integrator to write his/her own logic for deploying the necessary PHP applications, while still reusing a common base and reducing the workload. The role implements the following: * Creates a dedicated user/group for running the PHP scripts. * Creates a dedicated administrator user for maintaining the website. * Creates a base directory where the website-specific code and data should be stored at. * Adds nginx to website's group, so nginx could read the necessary files. * Adds website administrator to website's group, so administrator could manage the code and data. * Installs additional packages required for running the role (as configured). * Deploys the HTTPS TLS private key and certificate (for website vhost). * Configures PHP FPM and nginx to serve the website. The role is implemented with the following layout/logic in mind: * Clients are served with ``Strict-Transport-Security`` header with value of ``max-age=31536000; includeSubDomains``. This forces compliant clients to always connect using HTTPS to the web server when accessing its domain, as well as any subdomains served by this web server or any other. The (client-side) cached header value expires after one year. * Website users are named after the ``FQDN`` (fully qualified domain name) of website, in format of ``web-ESCAPEDFQDN``, where ``ESCAPEDFQDN`` is equal to ``FQDN`` where dots have been replaced by underscores (for example, ``web-cloud_example_com``). * Website users are set-up via GECOS field to have their umask set to ``0007`` (in combination with ``pam_umask``). * Administrator users are named after the ``FQDN`` (fully qualified domain name) of website, in format of ``admin-ESCAPEDFQDN``, where ``ESCAPEDFQDN`` is equal to ``FQDN`` where dots have been replaced by underscores (for example, ``admin-cloud_example_com``). * All websites reside within a dedicated sub-directory in ``/var/www``. The sub-directory name is equal to the ``FQDN`` used for accessing the website. Owner of the directory is set to be the application administrator, while group is set to be the website group. Additionally, ``SGID`` bit is set on the directory. This allows admin, with correct umask, to create necessary files and directories that should be readable (and eventually writeable) by the website user (running the PHP scripts) without having to become root. * All files placed in the website directory should be either created there directly, or copied to the directory in order to make sure the ``SGID`` gets honored. **Do not move the files, the permissions will not be set correctly.** * Within the website directory, nginx/php5-fpm will expect to find the relevant files within the htdocs sub-directory (this can be symlink too). * nginx communicates with PHP FPM over a dedicated Unix socket for each website. Role dependencies ~~~~~~~~~~~~~~~~~ Depends on the following roles: * **common** * **web_server** Parameters ~~~~~~~~~~ **additional_fpm_config** (dict, optional, ``{}``) Additional PHP FPM configuration options that should be included for PHP website's pool. Keys are parameter names, values are associated values. Don't forget to include quotes in the value itself if expected value type is string. **additional_nginx_config** (list, optional, ``[]``) List providing additional Nginx configuration options to include. This can be useful for specifying things like error pages. Options are applied inside of a **server** context of Nginx configuration file. Each item is a dictionary with the following options describing the extra configuration option: **comment** (string, mandatory) Comment describing the configuration option. **value** (string, mandatory) Configuration option. **admin_uid** (integer, optional, ``whatever OS picks``) UID of the dedicated website administrator user. The user will be member of website group. **deny_files_regex** (list, optional, ``[]``) List of regular expressions for matching files/locations to which the web server should deny access. This is useful to block access to any sensitive files that should not be served directly by the web server. The format must be compatible with regular expressions used by ``nginx`` for ``location ~`` syntax. **environment_indicator** (dictionary, optional, ``null``) Specify configuration for including environment indicator on all HTML pages. Indicator is a simple strip at bottom of a page with custom background colour, text colour, and text. Indicator can be collapsed by clicking on the arrows on the left side of the strip. Specifying environment indicator is useful for avoiding mistakes when testing by having better visibility what environment you are in (production/staging/test). The following keys need to be specified: **background_colour** (string, mandatory) Background colour to use for the strip at bottom. This should be value compatible with CSS ``background-color`` attribute. **text_colour** (string, mandatory) Text colour to use for the strip at bottom. This should be value compatible with CSS ``color`` attribute. **text** (string, mandatory) Text to show in show in the strip at bottom. **fqdn** (string, mandatory) Fully-qualified domain name where the website is reachable. This value is used for calculating the user/group name for dedicated website user, as well as home directory of the website user (where data/code should be stored at). **index** (string, optional, ``index.php``) Space-separated list of files which should be treated as index files by the web server. The web server will attempt opening these index files, in succession, until the first match, or until it runs out of matches, when a client requests an URI pointing to directory. **http_header_overrides** (dict, optional, ``{}``) HTTP headers to set/override on the incoming request before passing it on to the PHP application. Keys are HTTP header names, values are header values. .. note:: Role takes care of prefixing the headers with ``HTTP_``, converting them to upper-case, and replacing dashes with underscores - simply pass in the official HTTP header name, no extra precautions are required for PHP specifics. Double quotes in the value must be escaped with a backslash. Make sure to take into account the YAML escaping as well. For example, to set the value to ``this is quote - "``, YAML should look like one of the following: - ``this is double quote - "`` - ``'this is double quote - \"'`` - ``"this is double quote - \\\"'`` To clear a header value, simply set its value to an empty string. Nginx variables can be used as well, however keep in mind that the dollar sign (``$``) *cannot* be used/escaped due to Nginx configuration file syntax limitations. **https_tls_certificate** (string, mandatory) X.509 certificate used for TLS for HTTPS service. The file will be stored in directory ``/etc/ssl/certs/`` under name ``{{ fqdn }}_https.pem``. **https_tls_key** (string, optional, mandatory) Private key used for TLS for HTTPS service. The file will be stored in directory ``/etc/ssl/private/`` under name ``{{ fqdn }}_https.key``. **php_file_regex** (string, optional, ``\.php$``) Regular expression used for determining which file should be interepted via PHP. **php_rewrite_urls** (list, optional, ``[]``) A list of rewrite rules that are applied to incoming requests. These rewrite rules are specifically targetted at prettying-up the URLs used by the PHP scripts. Each element of the list should be a string value compatible with the format of ``nginx`` option ``rewrite``. The keyword ``rewrite`` itself should be omitted, as well as trailing semi-colon (``;``). **rewrites** (list, optional, ``[]``) A list of rewrite rules that are applied to incoming requests. Each element of the list should be a string value compatible with the format of ``nginx`` option ``rewrite``. The keyword ``rewrite`` itself should be omitted, as well as trailing semi-colon (``;``). **packages** (list, optional, ``[]``) A list of additional packages to install for this particular PHP appliction. This is usually going to be different PHP extensions. **uid** (integer, optional, ``whatever OS picks``) UID/GID (they are set-up to be the same) of the dedicated website user/group. **website_mail_recipients** (string, optional, ``root``) Space-separated list of e-mails or local users to which the mails, sent to either the website admin or website user, should be forwarded to. Forwarding is configured via ``~/.forward`` configuration file. Distribution compatibility ~~~~~~~~~~~~~~~~~~~~~~~~~~ Role is compatible with the following distributions: - Debian 11 (Bullseye) - Debian 12 (Bookworm) Examples ~~~~~~~~ Here is an example configuration for setting-up two (base) PHP websites (for running *ownCloud* and *The Bug Genie* applications): .. code-block:: yaml - role: php_website fqdn: cloud.example.com uid: 2001 php_file_regex: \.php($|/) rewrites: - ^/\.well-known/host-meta /public.php?service=host-meta - ^/\.well-known/host-meta\.json /public.php?service=host-meta-json - ^/\.well-known/carddav /remote.php/carddav/ redirect - ^/\.well-known/caldav /remote.php/caldav/ redirect - ^/apps/calendar/caldav\.php /remote.php/caldav/ - ^/apps/contacts/carddav\.php /remote.php/carddav/ - ^/remote/(.*) /remote.php deny_files_regex: - ^(\.|autotest|occ|issue|indie|db_|console|build/|tests/|config/|lib/|3rdparty/|templates/).* packages: # For ownCloud - php5-gd - php5-json - php5-mysql - php5-curl https_tls_key: "{{ lookup('file', inventory_dir + '/tls/cloud.example.com_https.key') }}" https_tls_certificate: "{{ lookup('file', inventory_dir + '/tls/cloud.example.com_https.pem') }}" additional_nginx_config: - comment: Use custom page for forbidden files. value: error_page 403 /core/templates/403.php; - comment: Use custom page for non-existing locations/files. value: error_page 404 /core/templates/404.php; additional_fpm_config: "env[PATH]": "\"/usr/local/bin:/usr/bin:/bin\"" website_mail_recipients: "root john.doe@example.com" environment_indicator: background_colour: "green" text_colour: "black" text: "TEST ENVIRONMENT" - role: php_website deny_files_regex: - ^\..* php_rewrite_urls: - ^(.*) /index.php?url=$1 fqdn: tbg.example.com uid: 2007 https_tls_key: "{{ lookup('file', inventory_dir + '/tls/tbg.example.com_https.key') }}" https_tls_certificate: "{{ lookup('file', inventory_dir + '/tls/tbg.example.com_https.pem') }}" WSGI Website ------------ The ``wsgi_website`` role can be used for setting-up a website powered by Python on destination machine. The website needs to use the WSGI specification for making the Python web application(s) available. This role is normally not supposed to be used directly, but should instead serve as the basis for writing website-specific roles. Therefore the role is written in quite generic way, allowing the integrator to write his/her own logic for deploying the necessary Python applications/packages, while still reusing a common base and reducing the workload. The role implements the following: * Creates a dedicated user/group for running the WSGI application. * Creates a dedicated administrator user for maintaining the website. * Creates a base directory where the website-specific code and data should be stored at. * Adds nginx to website's group, so nginx could read the necessary files. * Adds website administrator to website's group, so administrator could manage the code and data. * Installs additional packages required for running the role (as configured). * Sets-up a dedicated Python virtual environment for website. * Install Gunicorn in Python virtual environment. * Installs additional packages required for running the role in Python virtual environment (as configured). * Configures systemd to run the website code (using Gunicorn) * Deploys the HTTPS TLS private key and certificate (for website vhost). * Configures nginx to serve the website (static files served directly, requests passed on to Gunicorn). The role is implemented with the following layout/logic in mind: * No plaintext HTTP is allowed, HTTPS is mandatory. Clients connecting via plaintext HTTP are redirected to HTTPS. * Clients are served with ``Strict-Transport-Security`` header with value of ``max-age=31536000; includeSubDomains``. This forces compliant clients to always connect using HTTPS to the web server when accessing its domain, as well as any subdomains served by this web server or any other. The (client-side) cached header value expires after one year. * Website users are named after the ``FQDN`` (fully qualified domain name) of website, in format of ``web-ESCAPEDFQDN``, where ``ESCAPEDFQDN`` is equal to ``FQDN`` where dots have been replaced by underscores (for example, ``web-wiki_example_com``). * Website users are set-up via GECOS field to have their umask set to ``0007`` (in combination with ``pam_umask``). * Administrator users are named after the ``FQDN`` (fully qualified domain name) of website, in format of ``admin-ESCAPEDFQDN``, where ``ESCAPEDFQDN`` is equal to ``FQDN`` where dots have been replaced by underscores (for example, ``admin-cloud_example_com``). * All websites reside within a dedicated sub-directory in ``/var/www``. The sub-directory name is equal to the ``FQDN`` used for accessing the website. Owner of the directory is set to be the application administrator, while group is set to be the website group. Additionally, ``SGID`` bit is set on the directory. This allows admin, with correct umask, to create necessary files and directories that should be readable (and eventually writeable) by the website user (running the WSGI application) without having to become root. * All files placed in the website directory should be either created there directly, or copied to the directory in order to make sure the ``SGID`` gets honored. **Do not move the files, the permissions will not be set correctly.** * Within the website directory, Python virtual environment can be found within the ``virtualenv`` sub-directory. Switching to administrator user via login shell will automatically activate the virtual environment. * Within the website directory, nginx will expect to find the static files within the ``htdocs`` sub-directory (this can be symlink too). Locations/aliases can be configured for static file serving. * Within the website directory, systemd service will expect to find the website code within the ``code`` sub-directory (this can be symlink too). * nginx communicates with WSGI server over a dedicated Unix socket for each website. Role dependencies ~~~~~~~~~~~~~~~~~ Depends on the following roles: * **common** * **web_server** Parameters ~~~~~~~~~~ **additional_nginx_config** (list, optional, ``[]``) List providing additional Nginx configuration options to include. This can be useful for specifying things like error pages. Options are applied inside of a **server** context of Nginx configuration file. Each item is a dictionary with the following options describing the extra configuration option: **comment** (string, mandatory) Comment describing the configuration option. **value** (string, mandatory) Configuration option. **admin_uid** (integer, optional, ``whatever OS picks``) UID of the dedicated website administrator user. The user will be member of website group. **environment_indicator** (dictionary, optional, ``null``) Specify configuration for including environment indicator on all HTML pages. Indicator is a simple strip at bottom of a page with custom background colour, text colour, and text. Indicator can be collapsed by clicking on the arrows on the left side of the strip. Specifying environment indicator is useful for avoiding mistakes when testing by having better visibility what environment you are in (production/staging/test). The following keys need to be specified: **background_colour** (string, mandatory) Background colour to use for the strip at bottom. This should be value compatible with CSS ``background-color`` attribute. **text_colour** (string, mandatory) Text colour to use for the strip at bottom. This should be value compatible with CSS ``color`` attribute. **text** (string, mandatory) Text to show in show in the strip at bottom. **environment_variables** (dict, optional, ``{}``) Specify additional environment variables that should be set for running the service. Environment variables will be set in both the systemd service and for the application's administrator user (when logged in as one). **fqdn** (string, mandatory) Fully-qualified domain name where the website is reachable. This value is used for calculating the user/group name for dedicated website user, as well as home directory of the website user (where data/code should be stored at). **https_tls_certificate** (string, mandatory) X.509 certificate used for TLS for HTTPS service. The file will be stored in directory ``/etc/ssl/certs/`` under name ``{{ fqdn }}_https.pem``. **https_tls_key** (string, mandatory) Private key used for TLS for HTTPS service. The file will be stored in directory ``/etc/ssl/private/`` under name ``{{ fqdn }}_https.key``. **packages** (list, optional, ``[]``) A list of additional packages to install for this particular WSGI website. This is usually going to be development libraries for building Python packages. **http_header_overrides** (dict, optional, ``{}``) HTTP headers to set/override on the incoming request before passing it on to the WSGI application. Keys are HTTP header names, values are header values. Double quotes in the value must be escaped with a backslash. Make sure to take into account the YAML escaping as well. For example, to set the value to ``this is quote - "``, YAML should look like one of the following: - ``this is double quote - "`` - ``'this is double quote - \"'`` - ``"this is double quote - \\\"'`` To clear a header value, simply set its value to an empty string. Nginx variables can be used as well, however keep in mind that the dollar sign (``$``) *cannot* be used/escaped due to Nginx configuration file syntax limitations. **rewrites** (list, optional, ``[]``) A list of rewrite rules that are applied to incoming requests. Each element of the list should be a string value compatible with the format of ``nginx`` option ``rewrite``. The keyword ``rewrite`` itself should be omitted, as well as trailing semi-colon (``;``). **static_locations** (list, optional, ``[]``) List of locations that should be treated as static-only, and not processed by the WSGI application at all. This is normally used for designating serving of static/media files by Nginx (for example, in case of Django projects for ``/static/`` and ``/media/``). **uid** (integer, optional, ``whatever OS picks``) UID/GID (they are set-up to be the same) of the dedicated website user/group. **use_paste** (boolean, optional, ``False``) Tell Gunicorn to assume that the passed-in ``wsgi_application`` value is a filename of a Python Paste ``ini`` file instead of WSGI application. **virtuaelnv_packages** (list, optional, ``[]``) A list of additional packages to install for this particular WSGI appliction in its virtual environment using ``pip``. **website_mail_recipients** (string, optional, ``root``) Space-separated list of e-mails or local users to which the mails, sent to either the website admin or website user, should be forwarded to. Forwarding is configured via ``~/.forward`` configuration file. **wsgi_application** (string, mandatory) WSGI application that should be started by Gunicorn. The format should be conformant to what the ``gunicorn`` command-line tool accepts. If the ``use_paste`` option is enabled, the value should be equal to filename of the Python Paste ini file, located in the ``code`` sub-directory. It should be noted that in either case the value should be specsified relative to the ``code`` sub-directory. I.e. don't use full paths. **wsgi_requirements** (list, optional, ``[ gunicorn==21.2.0, packaging==23.2 ]``) Complete list of pip requirements used for deploying Gunicorn. If specified, this list will be used to create requirements file and install Gunicorn and its dependencies from that one. This allows to have pinned packages for both Gunicorn and its dependencies. It should be noted that this installation method is meant primarily in case of roles that want to take advantage of upgrade checks for pip requirements files, and that employ `pip-tools `_. In addition to change of installation method, when this parameter is specified the role will deploy necessary files for running the pip requirements upgrade check (see the ``common`` role for description). For this a directory is created under ``/etc/pip_check_requirements_upgrades/FQDN``. The same directory should be used by dependant roles to deploy their own ``.in`` and ``.txt`` files. Make sure the file ownership is set to ``root:pipreqcheck``. Should you need to utilise the requirements file in some manner (other than checking for its upgrades), it will be also stored (and made accessible to application user/admin)) in application's home directory under the name ``.wsgi_requirements.txt``. To create complete requirements list, it is recommended to use `pip-tools `_ (the ``pip-compile`` utility) with ``gunicorn`` and ``futures`` in the ``.in.`` file. **wsgi_requirements_in** (list, optional, ``[ gunicorn ]``) List of top level packages to use when performing the pip requirements upgrade checks for the Gunicorn requirements (listed via ``wsgi_requirements`` parameter). Distribution compatibility ~~~~~~~~~~~~~~~~~~~~~~~~~~ Role is compatible with the following distributions: - Debian 11 (Bullseye) - Debian 12 (Bookworm) Examples ~~~~~~~~ Here is an example configuration for setting-up a (base) WSGI website (for running a bare Django project): .. code-block:: yaml # Sample for a Django installation. - role: wsgi_website fqdn: django.example.com static_locations: - /static - /media uid: 2004 virtualenv_packages: - django wsgi_application: django_example_com.wsgi:application environment_variables: DJANGO_SETTINGS_MODULE: "django_example_com.settings.production" https_tls_key: "{{ lookup('file', inventory_dir + '/tls/wsgi.example.com_https.key') }}" https_tls_certificate: "{{ lookup('file', inventory_dir + '/tls/wsgi.example.com_https.pem') }}" additional_nginx_config: - comment: Use custom page for forbidden files. value: error_page 403 /static/403.html; - comment: Use custom page for non-existing locations/files. value: error_page 404 /static/404.html; website_mail_recipients: "root john.doe@example.com" environment_indicator: background_colour: "green" text_colour: "black" text: "TEST ENVIRONMENT" http_header_overrides: Accept-Encoding: "" # Use wsgi_requirements to deploy Gunicorn. - role: wsgi_website fqdn: wsgi.example.com wsgi_application: wsgi:main wsgi_requirements: - gunicorn==19.7.1 - futures==3.1.1 Database Server --------------- The ``database_server`` role can be used for setting-up a MariaDB database server on destination machine. The role implements the following: * Installs MariaDB server and client. * Configures MariaDB server and client to use *UTF-8* encoding by default. * Sets-up the database root user for passwordless login via UNIX socket authentication. Role dependencies ~~~~~~~~~~~~~~~~~ Depends on the following roles: * **common** Parameters ~~~~~~~~~~ This role has no parameters. Distribution compatibility ~~~~~~~~~~~~~~~~~~~~~~~~~~ Role is compatible with the following distributions: - Debian 11 (Bullseye) - Debian 12 (Bookworm) Examples ~~~~~~~~ This role has no parameters which can be configured configure. Database -------- The ``database`` role can be used for creating a MariaDB database and accompanying user on destination machine. The role implements the following: * Creates MariaDB database. * Creates a dedicated user capable of performing any operation on the created database. Username is set to be same as the name of database. * Sets-up pre-backup task that creates database dump in location ``/srv/backup/mariadb/{{ db_name }}.sql``. Role dependencies ~~~~~~~~~~~~~~~~~ Depends on the following roles: * **database_server** * **backup_client** Backups ~~~~~~~ If the backup for this role has been enabled, the following paths are backed-up: **/srv/backup/maraidb/{{ db_name }}.sql** Dump of the database. Database dump is created every day at 01:45 in the morning. Parameters ~~~~~~~~~~ **db_name** (string, mandatory) Name of the database that should be created. **db_password** (string, mandatory) Password for the database user. Distribution compatibility ~~~~~~~~~~~~~~~~~~~~~~~~~~ Role is compatible with the following distributions: - Debian 11 (Bullseye) - Debian 12 (Bookworm) Examples ~~~~~~~~ Here is an example configuration for creating a single database (for some website): .. code-block:: yaml - role: database db_name: phpinfo_example_com db_password: phpinfo_example_com Backup Server ------------- The ``backup_server`` role can be used for setting-up a server to act as backup storage for the backup clients. Storage is made available to the clients exclusively via SFTP on a dedicated port and dedicated OpenSSH server instance. This instance is specifically configured and tailored for this purpose. The role is primarily aimed for use with `Duplicity `_, but should be also usable for generic SFTP uploads. The role implements the following: * Installs backup software (Duplicity, Duply). * Creates a dedicated directory structure for backups with the following structure: * ``/srv/backups/`` - main directory under which all the backups reside. * ``/srv/backups/SERVER_NAME/`` - home directory for the backup user, name after the server. Backup users are confined to their respective home directory via chroot. Backup users can't write to their own home directory, though. * ``/srv/backups/SERVER_NAME/duplicity/`` - directory where the Duplicity backups are stored at. This directory is writable by the respective backup user. * ``SERVER_NAME/.ssh/`` - directory where authorized keys are stored. Backup user is not allowed to make modifications to this directory and files contained within (i.e. backup users can't add more keys to the ``authorized_keys`` file). * Creates dedicated operating system users for backup clients. These users will be made members of the ``backup`` group as well (as an additional group). * Sets-up ``authorized_keys`` for the backup clients. * Makes sure the backup users can't log-in via regular OpenSSH server instance. * Sets-up dedicated OpenSSH server instances to be used exclusively by backup clients. The instance listens on TCP port ``2222``. * Updates firewall to allow incoming TCP connections to port ``2222``. Connections are allowed only from the configured IP addresses associated with backup clients. Role dependencies ~~~~~~~~~~~~~~~~~ Depends on the following roles: * **common** Parameters ~~~~~~~~~~ **backup_clients** (list, optional) List of backup clients that are connecting to the backup server. This is usually done on a per-server basis. Each item in the list is a dictionary describing the backup client. The following keys are available: **server** (string, mandatory) Name of the server that is backed up. It is highly recommended to use server's FQDN for this purpose. The dedicated operating system user created will have the name of format ``bak-ESCAPED_SERVER_NAME``, where ``ESCAPED_SERVER_NAME`` is calculated by taking the passed-in server name and replacing all dots (``.``) with undescores (``_``). For example, ``web.example.com`` will be turned into ``bak-web_example_com``. **uid** (integer, optional, ``whatever OS picks``) Uid for the operating system user. User's default group will have a GID identical to the user's UID if specified. Otherwise user's default group will have OS-determined GID. **ip** (IPv4 address, mandatory) IPv4 address from which the backup client server is connecting to the backup server. Used for introducing stricter firewall rules. **public_key** (string, mandatory) SSH public key used by backup client to connect to the backup server. **backup_host_ssh_private_keys** (dictionary, mandatory) Defines host keys used for the dedicated OpenSSH server instance for backup. Key values that must be provided are: - **rsa** - **ed25519** - **ecdsa** Values for each key should be the corresponding private key generated using the appropriate algorithm. Keys for this purpose can be easily created via commands:: ssh-keygen -f backup_server_rsa_key -N '' -t rsa ssh-keygen -f backup_server_ed25519_key -N '' -t ed25519 ssh-keygen -f backup_server_ecdsa_key -N '' -t ecdsa Distribution compatibility ~~~~~~~~~~~~~~~~~~~~~~~~~~ Role is compatible with the following distributions: - Debian 11 (Bullseye) - Debian 12 (Bookworm) Examples ~~~~~~~~ Here is an example configuration for setting-up the backup server role: .. code-block:: yaml - role: backup_server backup_clients: - server: web.example.com uid: 3000 public_key: "{{ lookup('file', inventory_dir + '/ssh/web.example.com.pub') }}" ip: 10.32.64.18 - server: mail.example.com public_key: "{{ lookup('file', inventory_dir + '/ssh/mail.example.com.pub') }}" ip: 10.32.64.15 backup_host_ssh_private_keys: rsa: "{{ lookup('file', inventory_dir + '/ssh/backup_server_rsa_key') }}" ed25519: "{{ lookup('file', inventory_dir + '/ssh/backup_server_ed25519_key') }}" ecdsa: "{{ lookup('file', inventory_dir + '/ssh/backup_server_ecdsa_key') }}" Backup Client ------------- The ``backup_client`` role can be used for setting-up the server as a backup client so it can perform backups to the backup server. Backup clients utilise duplicity (via the duply convenience wrapper) for performing the backups to a backup server via *SFTP* protocol. The role itself will take care of deploying the necessary software, configuration files, and encryption/signing private key to the backup client in order to be able to perform backup. Files that should be backed-up are specified using the ``backup`` role. The role implements the following: * Installs backup software (Duplicity, Duply). * Sets-up Duply configuration under directory ``/etc/duply/main/``. * Deploys encryption/signing private key (usually host-specific), as well as additional encryption public keys to the server, and imports them into local GnuPG keyring used by backup software. * Deploys private SSH key for logging-in into the backup server over SFTP. * Deploys ``known_hosts`` file for SFTP fingerprint verification. * Sets-up a handler that runs scripts/binaries before the actual backup run. This is helpful for producing database backups. Such scripts/binaries should be deployed to directory ``/etc/duply/main/pre.d/``, and marked executable by the root user. Duply is configured as follows: * GnuPG keyring is stored under ``/etc/duply/main/gnupg/``. The keyring should not be managed manually. * SSH private key for logging-in into backup server is stored in location ``/etc/duply/main/ssh/identity``. Backup server SFTP fingerprint is stored in location ``/etc/duply/main/ssh/known_hosts``. * Base directory for back-ups is root (``/``), but *all* files are excluded by default to prevent huge back-ups. Ansible roles that want to utilise the backup client role can specify which patterns should be included in the backup when including the ``backup`` role. Include pattern file is assembled and stored in location ``/etc/duply/main/include``. * Backups are encrypted and signed with the specified encryption key. * Maximum age for old backups is set to 6 months. * Maximum age for full backups is set to 1 month. * Volume size is set to 1GB. * Pre-backup scripts are run via ``/etc/duply/main/pre`` handler that tries to execute scripts/binaries from directory ``/etc/duply/main/pre.d/``. * Pre-backup scripts must run successfully for the actual backup process to proceed. * Old backups are automatically purged in case of successful run. .. note:: Since at time of this writing there are no lookup plugins for extracting key material/information from GnuPG keyring, you may want to resort to extraction of keys on the controller machine via lookups similar to:: lookup('pipe', 'gpg2 --homedir /path/to/your/keyring --armor --export some_identifier') lookup('pipe', 'gpg2 --homedir /path/to/your/keyring --armor --export-secret-keys some_identifier') This may not be the most elegant solution, but for now it offers better flexibility (theoretically, you could store all those keys etc as plaintext files instead). Parameters ~~~~~~~~~~ **backup_additional_encryption_keys** (list, optional, ``[]``) List of additional public encryption keys used for backup operation. Each item in the list should be an ASCII armour-encoded public key exported from a GnuPG keyring. These additional public keys are useful in cases where the backups should be decryptable with some master key in addition to server-specific key. **backup_client_username** (string, optional, ``bak-{{ ansible_fqdn | replace('.', '_') }}``) Username for connecting to the backup server via SFTP. **backup_encryption_key** (string, mandatory) Private GnuPG key, encoded using ASCII armor, used for encryption and signing operations when running the backup on the client server. This *must* be a private key! This is normally host-specific encryption key that is distributed to destination server and that can be also used for the restore operations (for data decryption). The key must not be password-protected. **backup_server** (string, mandatory) Backup server to connect to. **backup_server_destination** (string, optional, ``/duplicity``) Target directory on the backup server where the backups are stored. **backup_server_host_ssh_public_keys** (list, mandatory) SSH public keys presented by the server during client authentication. These public keys are used for populating the known hosts on the backup client side for host verification purposes. **backup_server_port** (int, optional, ``2222``) Port on the backup server to connect to for accessing the SFTP service. **backup_ssh_key** (string, mandatory) SSH private key for logging-in into the backup server. Distribution compatibility ~~~~~~~~~~~~~~~~~~~~~~~~~~ Role is compatible with the following distributions: - Debian 11 (Bullseye) - Debian 12 (Bookworm) Examples ~~~~~~~~ Here is an example configuration for setting-up the role (take note that lookup plugin is quite useful here for fetching key values from some local directory): .. code-block:: yaml - role: backup_client backup_additional_encryption_keys: "-----BEGIN PGP PUBLIC KEY BLOCK-----\n...\n-----END PGP PUBLIC KEY BLOCK-----" backup_client_username: "user" backup_encryption_key: "-----BEGIN PGP PRIVATE KEY BLOCK-----\n...\n-----END PGP PRIVATE KEY BLOCK-----" backup_server: "backup.example.com" backup_server_destination: "//example/host" backup_server_host_ssh_public_keys: - "{{ lookup('file', inventory_dir + '/ssh/backup_server_ecdsa_key.pub') }}" - "{{ lookup('file', inventory_dir + '/ssh/backup_server_ed25519_key.pub') }}" - "{{ lookup('file', inventory_dir + '/ssh/backup_server_rsa_key.pub') }}" backup_server_port: 22 backup_ssh_key: "{{ lookup('file', inventory_dir + '/ssh/web.example.com') }}" Backup ------ The ``backup`` role can be used to specify what files should be backed-up to the backup server. The role provides a convenient way to deploy a file containing file and directory patterns describing the file/directory paths that should be included in the back-up. The role implements the following: * Installs a file with provided patterns in directory ``/etc/duply/main/patterns/``. * Assembles/refresshes the main include pattern file at ``/etc/duply/main/include``. Role dependencies ~~~~~~~~~~~~~~~~~ Depends on the following roles: * **backup_client** Parameters ~~~~~~~~~~ **backup_patterns_filename** (string, mandatory) Name of the backup patterns file. The file is stored in directory ``/etc/duply/main/patterns/``. This should be a unique filename amongst all roles. If role can be included multiple times, make sure the filename is always unique when depending on the backup role. **backup_patterns** (list, optional, ``[]``) List of globbing patterns defining which files or directories should be backed-up. Distribution compatibility ~~~~~~~~~~~~~~~~~~~~~~~~~~ Role is compatible with the following distributions: - Debian 11 (Bullseye) - Debian 12 (Bookworm) Examples ~~~~~~~~ Here is an example configuration for setting-up the role: .. code-block:: yaml - role: backup backup_patterns_filename: myapp backup_patters: - /var/www/myapp.example.com