diff --git a/docs/rolereference.rst b/docs/rolereference.rst index 7dbaf3b928dba46fc3a05635fc5edb48b3aeb63f..cf021019a08b9007dfefac7f02b01a5ca0432916 100644 --- a/docs/rolereference.rst +++ b/docs/rolereference.rst @@ -21,14 +21,14 @@ deployment. This section lists such parameters. **tls_private_key_dir** (string, optional if paths to private keys for all roles are explicitly specified) Path to directory on Ansible host that contains the private keys used by - services deployed by various roles. When TLS key path is not explicitly - defined in a role, this is the directory where the TLS key will be looked-up - during Ansible run. Expected filename pattern is ``FQDN_SERVICE.key`` (for - example, ``mail.example.com_smtp.key`` or ``xmpp.example.com_xmpp.key``). + services deployed by various roles. When TLS keys are not explicitly defined + in a role, this is the directory where the TLS key will be looked-up during + Ansible run. Expected filename pattern is ``FQDN_SERVICE.key`` (for example, + ``mail.example.com_smtp.key`` or ``xmpp.example.com_xmpp.key``). **tls_certificate_dir** (string, optional if paths to certificate files for all roles are explicitly specified) Path to directory on Ansible host that contains the X.509 certificate files - used by services deployed by various roles. When X.509 certificate path is not + used by services deployed by various roles. When X.509 certificate is not explicitly defined in a role, this is the directory where the X.509 certificate will be looked-up during Ansible run. Expected filename pattern is ``FQDN_SERVICE.pem`` (for example, ``mail.example.com_smtp.pem`` or @@ -575,13 +575,13 @@ Parameters ` for value description and syntax. -**ldap_server_tls_certificate** (string, optional, ``{{ tls_certificate_dir }}/{{ ansible_fqdn }}_ldap.pem``) - Path to file on Ansible host that contains the X.509 certificate used for TLS - for LDAP service. The file will be copied to directory ``/etc/ssl/certs/``. +**ldap_server_tls_certificate** (string, optional, ``{{ lookup('file', tls_certificate_dir + '/' ansible_fqdn + '_ldap.pem') }}``) + 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, optional, ``{{ tls_private_key_dir }}/{{ ansible_fqdn }}_ldap.key``) - Path to file on Ansible host that contains the private key used for TLS for - LDAP service. The file will be copied to directory ``/etc/ssl/private/``. +**ldap_server_tls_key** (string, optional, ``{{ lookup('file', tls_private_key_dir + '/' ansible_fqdn + '_ldap.key') }}``) + 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 @@ -600,8 +600,8 @@ Here is an example configuration for setting-up LDAP server: ldap_server_domain: "example.com" ldap_server_organization: "Example Corporation" ldap_server_log_level: 256 - ldap_server_tls_certificate: ~/tls/ldap.example.com_ldap.pem - ldap_server_tls_key: ~/tls/ldap.example.com_ldap.key + 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: @@ -726,13 +726,13 @@ Parameters Fully qualified domain name, hostname, or IP address of the LDAP server used for user authentication and listing. -**xmpp_tls_certificate** (string, optional, ``{{ tls_certificate_dir }}/{{ ansible_fqdn }}_xmpp.pem``) - Path to file on Ansible host that contains the X.509 certificate used for TLS - for SMTP service. The file will be copied to directory ``/etc/ssl/certs/``. +**xmpp_tls_certificate** (string, optional, ``{{ lookup('file', tls_certificate_dir + '/' + fqdn + '_xmpp.pem') }}``) + 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, optional, ``{{ tls_private_key_dir }}/{{ ansible_fqdn }}_xmpp.key``) - Path to file on Ansible host that contains the private key used for TLS for - XMPP service. The file will be copied to directory ``/etc/ssl/private/``. +**xmpp_tls_key** (string, optional, ``{{ lookup('file', tls_private_key_dir + '/' + fqdn + '_xmpp.key') }}``) + Private key used for TLS for XMPP service. The file will be stored in + directory ``/etc/ssl/private/`` under name ``{{ ansible_fqdn }}_xmpp.key``. Examples @@ -753,8 +753,8 @@ Here is an example configuration for setting-up XMPP server using Prosody: 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: /etc/prosody/certs/localhost.key - xmpp_tls_certificate: /etc/prosody/certs/localhost.crt + xmpp_tls_key: "{{ lookup('file', '/etc/prosody/certs/localhost.key') }}" + xmpp_tls_certificate: "{{ lookup('file', '/etc/prosody/certs/localhost.crt') }}" Mail Server @@ -864,23 +864,21 @@ Parameters **mail_user_gid** (integer, optional, ``whatever OS picks``) GID of the user that owns all the mail files. -**imap_tls_certificate** (string, optional, ``{{ tls_certificate_dir }}/{{ ansible_fqdn }}_imap.pem``) - Path to file on Ansible host that contains the X.509 certificate used for TLS - for IMAP and ManageSieve services. The file will be copied to directory - ``/etc/ssl/certs/``. +**imap_tls_certificate** (string, optional, ``{{ lookup('file', tls_certificate_dir + '/' ansible_fqdn + '_imap.pem') }}``) + 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, optional, ``{{ tls_private_key_dir }}/{{ ansible_fqdn }}_imap.key``) - Path to file on Ansible host that contains the private key used for TLS for - IMAP and ManageSieve services. The file will be copied to directory - ``/etc/ssl/private/``. +**imap_tls_key** (string, optional, ``{{ lookup('file', tls_private_key_dir + '/' ansible_fqdn + '_imap.key') }}``) + Private key used for TLS for IMAP service. The file will be stored in + directory ``/etc/ssl/private/`` under name ``{{ ansible_fqdn }}_imap.key``. -**smtp_tls_certificate** (string, optional, ``{{ tls_certificate_dir }}/{{ ansible_fqdn }}_smtp.pem``) - Path to file on Ansible host that contains the X.509 certificate used for TLS - for SMTP service. The file will be copied to directory ``/etc/ssl/certs/``. +**smtp_tls_certificate** (string, optional, ``{{ lookup('file', tls_certificate_dir + '/' ansible_fqdn + '_smtp.pem') }}``) + 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, optional, ``{{ tls_certificate_dir }}/{{ ansible_fqdn }}_smtp.key``) - Path to file on Ansible host that contains the private key used for TLS for - SMTP service. The file will be copied to directory ``/etc/ssl/private/``. +**smtp_tls_key** (string, optional, ``{{ lookup('file', tls_private_key_dir + '/' ansible_fqdn + '_smtp.key') }}``) + 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 @@ -919,10 +917,10 @@ Here is an example configuration for setting-up XMPP server using Prosody: mail_user_uid: 5000 mail_user_gid: 5000 - imap_tls_certificate: ~/tls/mail.example.com_imap.pem - imap_tls_key: ~/tls/mail.example.com_imap.key - smtp_tls_certificate: ~/tls/mail.example.com_smtp.pem - smtp_tls_key: ~/tls/mail.example.com_smtp.key + 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 @@ -1041,15 +1039,13 @@ Parameters Specify if HTTPS should be enforced for the default virtual host or not. If enforced, clients connecting via plaintext will be redirected to HTTPS. -**default_https_tls_key** (string, optional, ``{{ tls_private_key_dir }}/{{ ansible_fqdn }}_https.key``) - Path to file on Ansible host that contains the private key used for TLS for - HTTPS service. The file will be copied to directory - ``/etc/ssl/private/``. This key is used for the default virrtual host. +**default_https_tls_certificate** (string, optional, ``{{ lookup('file', tls_certificate_dir + '/' + ansible_fqdn + '_https.pem') }}``) + 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_certificate** (string, optional, ``{{ tls_certificate_dir }}/{{ ansible_fqdn }}_https.pem``) - Path to file on Ansible host that contains the X.509 certificate used for TLS - for HTTPS service. The file will be copied to directory - ``/etc/ssl/certs/``. This certificate is used for the default virrtual host. +**default_https_tls_key** (string, optional, ``{{ lookup('file', tls_private_key_dir + '/' + ansible_fqdn + '_https.key') }}``) + Private key used for TLS for HTTPS service. The file will be stored in + directory ``/etc/ssl/private/`` under name ``{{ ansible_fqdn }}_https.key``. **web_default_title** (string, optional, ``Welcome``) Title for the default web page shown to users (if no other vhosts were matched). @@ -1068,8 +1064,8 @@ Here is an example configuration for setting-up web server: --- - default_https_tls_key: "{{ inventory_dir }}/tls/web.example.com_https.key" - default_https_tls_certificate: "{{ inventory_dir }}/tls/web.example.com_https.pem" + 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." @@ -1159,13 +1155,13 @@ Parameters succession, until the first match, or until it runs out of matches, when a client requests an URI pointing to directory. -**https_tls_certificate** (string, optional, ``{{ tls_certificate_dir }}/{{ fqdn }}_https.pem``) - Path to file on Ansible host that contains the X.509 certificate used for TLS - for HTTPS service. The file will be copied to directory ``/etc/ssl/certs/``. +**https_tls_certificate** (string, optional, ``{{ lookup('file', tls_certificate_dir + '/' + fqdn + '_https.pem') }}``) + 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, ``{{ tls_private_key_dir }}/{{ fqdn }}_https.key``) - Path to file on Ansible host that contains the private key used for TLS for - HTTPS service. The file will be copied to directory ``/etc/ssl/private/``. +**https_tls_key** (string, optional, ``{{ lookup('file', tls_private_key_dir + '/' + fqdn + '_https.key') }}``) + 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 @@ -1222,8 +1218,8 @@ running *ownCloud* and *The Bug Genie* applications): - php5-json - php5-mysql - php5-curl - https_tls_key: "{{ inventory_dir }}/tls/cloud.example.com_https.key" - https_tls_certificate: "{{ inventory_dir }}/tls/cloud.example.com_https.pem" + 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') }}" - role: php_website admin: admin deny_files_regex: @@ -1232,8 +1228,8 @@ running *ownCloud* and *The Bug Genie* applications): - ^(.*) /index.php?url=$1 fqdn: tbg.example.com uid: 2007 - https_tls_key: "{{ inventory_dir }}/tls/tbg.example.com_https.key" - https_tls_certificate: "{{ inventory_dir }}/tls/tbg.example.com_https.pem" + 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 @@ -1322,13 +1318,13 @@ Parameters 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, optional, ``{{ tls_certificate_dir }}/{{ fqdn }}_https.pem``) - Path to file on Ansible host that contains the X.509 certificate used for TLS - for HTTPS service. The file will be copied to directory ``/etc/ssl/certs/``. +**https_tls_certificate** (string, optional, ``{{ lookup('file', tls_certificate_dir + '/' + fqdn + '_https.pem') }}``) + 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, ``{{ tls_private_key_dir }}/{{ fqdn }}_https.key``) - Path to file on Ansible host that contains the private key used for TLS for - HTTPS service. The file will be copied to directory ``/etc/ssl/private/``. +**https_tls_key** (string, optional, ``{{ lookup('file', tls_private_key_dir + '/' + fqdn + '_https.key') }}``) + 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 @@ -1384,8 +1380,8 @@ running a bare Django project): virtualenv_packages: - django wsgi_application: django_example_com.wsgi:application - https_tls_key: "{{ inventory_dir }}/tls/wsgi.example.com_https.key" - https_tls_certificate: "{{ inventory_dir }}/tls/wsgi.example.com_https.pem" + 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') }}" Database Server