From d36a238c0dd51667c82084d317c1ce576e6b07b3 2020-08-25 22:51:43 From: Branko Majic Date: 2020-08-25 22:51:43 Subject: [PATCH] MAR-162: Updated usage instructions: - Create directory for storing TLS artefacts during base set-up of control machine. - Use full paths to TLS artefacts for parameters. - Fix the name of TLS parameters for the XMPP server role. --- diff --git a/docs/usage.rst b/docs/usage.rst index 3defa3f95c1835a717807585e4202a293863430c..08bac3b66f222abeef0fcdf1d2fc0a6ef65143a7 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -232,6 +232,7 @@ First of all, let's set-up some basic directory structure and configuration: mkdir ~/mysite/playbooks/ mkdir ~/mysite/group_vars/ mkdir ~/mysite/ssh/ + mkdir ~/mysite/tls/ mkdir ~/mysite/gnupg/ 5. Create SSH private/public key pair that will be used by Ansible for @@ -262,7 +263,8 @@ public CAs, or perhaps go for a mix of both. For the purpose of this guide, we'll set-up a small simple local CA to issue all the necessary certificates, and we'll generate the private -keys and issue server certificates on the go as needed. +keys and issue server certificates on the go as needed, storing them +all under the ``~/mysite/tls/`` directory. So, let us make a slight detour to create a CA of our own: @@ -272,12 +274,7 @@ So, let us make a slight detour to create a CA of our own: apt-get install -y gnutls-bin -2. Create directory where the private keys and certificates will be - stored at (you can switch back to the ``ansible`` user now):: - - mkdir ~/mysite/tls/ - -3. Create a template for the ``certtool`` so it would know what +2. Create a template for the ``certtool`` so it would know what extensions and content to have in the CA certificate: :file:`~/mysite/tls/ca.cfg` @@ -291,13 +288,13 @@ So, let us make a slight detour to create a CA of our own: cert_signing_key crl_signing_key -4. Almost there... Now let us generate the CA private key and +3. Almost there... Now let us generate the CA private key and self-signed certificate:: certtool --sec-param high --generate-privkey --outfile ~/mysite/tls/ca.key certtool --template ~/mysite/tls/ca.cfg --generate-self-signed --load-privkey ~/mysite/tls/ca.key --outfile ~/mysite/tls/ca.pem -5. And just one more small tweak - we need to provide a truststore PEM +4. And just one more small tweak - we need to provide a truststore PEM file containing all CA certificates in the chain for services to be able to connect to each-other (where necessary). In this particular case we have a super-simple hierarchy (root CA is also issuing the @@ -632,8 +629,8 @@ one up first. This includes both the LDAP *server* and *client* configuration. ldap_admin_password: admin ldap_server_organization: "Example Inc." - ldap_server_tls_certificate: "{{ lookup('file', 'tls/comms.example.com_ldap.pem') }}" - ldap_server_tls_key: "{{ lookup('file', 'tls/comms.example.com_ldap.key') }}" + ldap_server_tls_certificate: "{{ lookup('file', '~/mysite/tls/comms.example.com_ldap.pem') }}" + ldap_server_tls_key: "{{ lookup('file', '~/mysite/tls/comms.example.com_ldap.key') }}" 4. Phew. That was... Well, actually, easy :) Technically, only the LDAP admin password and TLS certificate/key *must* be set, but it @@ -777,16 +774,16 @@ role. mail_user_gid: 5000 # Set private keys and certificates to use for the IMAP service. - imap_tls_certificate: "{{ lookup('file', 'tls/comms.example.com_imap.pem') }}" - imap_tls_key: "{{ lookup('file', 'tls/comms.example.com_imap.key') }}" + imap_tls_certificate: "{{ lookup('file', '~/mysite/tls/comms.example.com_imap.pem') }}" + imap_tls_key: "{{ lookup('file', '~/mysite/tls/comms.example.com_imap.key') }}" # Set private keys and certificates to use for the SMTP service. - smtp_tls_certificate: "{{ lookup('file', 'tls/comms.example.com_smtp.pem') }}" - smtp_tls_key: "{{ lookup('file', 'tls/comms.example.com_smtp.key') }}" + smtp_tls_certificate: "{{ lookup('file', '~/mysite/tls/comms.example.com_smtp.pem') }}" + smtp_tls_key: "{{ lookup('file', '~/mysite/tls/comms.example.com_smtp.key') }}" # Set the X.509 certificate truststore to use for validating the # LDAP server certificate. - mail_ldap_tls_truststore: "{{ lookup('file', 'tls/truststore.pem') }}" + mail_ldap_tls_truststore: "{{ lookup('file', '~/mysite/tls/truststore.pem') }}" 3. There are two distinct mail services that need to access the LDAP directory - *Postfix* (serving as an SMTP server), and *Dovecot* (serving as an IMAP @@ -1062,8 +1059,8 @@ role. :: # Set the TLS private key and certificate. - xmpp_server_tls_certificate: "{{ lookup('file', 'tls/comms.example.com_xmpp.pem') }}" - xmpp_server_tls_key: "{{ lookup('file', 'tls/comms.example.com_xmpp.key') }}" + xmpp_tls_certificate: "{{ lookup('file', '~/mysite/tls/comms.example.com_xmpp.pem') }}" + xmpp_tls_key: "{{ lookup('file', '~/mysite/tls/comms.example.com_xmpp.key') }}" # Set one of the users to also be an XMPP administrator. xmpp_administrators: @@ -1240,8 +1237,8 @@ Nginx. --- - default_https_tls_certificate: "{{ lookup('file', 'tls/www.example.com_https.pem') }}" - default_https_tls_key: "{{ lookup('file', 'tls/www.example.com_https.key') }}" + default_https_tls_certificate: "{{ lookup('file', '~/mysite/tls/www.example.com_https.pem') }}" + default_https_tls_key: "{{ lookup('file', '~/mysite/tls/www.example.com_https.key') }}" web_default_title: "Welcome to default page!" web_default_message: "Nothing to see here, move along..." @@ -1418,8 +1415,8 @@ Before we start, here is a couple of useful pointers regarding the # Our virtual host will for PHP website will respond to this name. fqdn: tbg.example.com # TLS key and certificate to use for the virtual host. - https_tls_certificate: "{{ lookup('file', 'tls/tbg.example.com_https.pem') }}" - https_tls_key: "{{ lookup('file', 'tls/tbg.example.com_https.key') }}" + https_tls_certificate: "{{ lookup('file', '~/mysite/tls/tbg.example.com_https.pem') }}" + https_tls_key: "{{ lookup('file', '~/mysite/tls/tbg.example.com_https.key') }}" # Some additional packages are required in order to deploy and use TBG. packages: - php-gd @@ -1736,8 +1733,8 @@ on the safe side: - role: wsgi_website fqdn: wiki.example.com # TLS key and certificate to use for the virtual host. - https_tls_certificate: "{{ lookup('file', 'tls/wiki.example.com_https.pem') }}" - https_tls_key: "{{ lookup('file', 'tls/wiki.example.com_https.key') }}" + https_tls_certificate: "{{ lookup('file', '~/mysite/tls/wiki.example.com_https.pem') }}" + https_tls_key: "{{ lookup('file', '~/mysite/tls/wiki.example.com_https.key') }}" # In many cases you need to have some development packages available # in order to build Python packages installed via pip packages: