diff --git a/docs/testsite.rst b/docs/testsite.rst index 0f3d142119cd033b81f1b4e2e12167925c2846aa..0aaafa6f1b8004717d32624a817af498043d9c60 100644 --- a/docs/testsite.rst +++ b/docs/testsite.rst @@ -38,22 +38,46 @@ site.yml In order to deploy the test site, the following steps would normally be taken: -1. Generate the preseed files: +1. Create TLS private keys (relative to top level directory): + + - ``testsite/tls/mail.example.com_imap.key`` + - ``testsite/tls/mail.example.com_smtp.key`` + - ``testsite/tls/xmpp.example.com_xmpp.key`` + - ``testsite/tls/ldap.example.com_ldap.key`` + +2. Issue TLS certificates corresponding to the generated TLS private keys (make + sure to use correct FQDN for DNS subject alternative name): + + - ``testsite/tls/mail.example.com_imap.pem`` (subject alternative name should + be ``mail.example.com``) + - ``testsite/tls/mail.example.com_smtp.pem`` (subject alternative name should + be ``mail.example.com``) + - ``testsite/tls/xmpp.example.com_xmpp.pem`` (subject alternative name should + be ``xmpp.example.com``) + - ``testsite/tls/ldap.example.com_ldap.pem`` (subject alternative name should + be ``ldap.example.com``) + +3. Create ``PEM`` truststore file which contains all CA certificates that form + CA chain for the issued end entity certificates from previous step at + location ``testsite/tls/example_ca_chain.crt``. It is very important to + include the CA chain used for LDAP server. + +4. Generate the preseed files: .. code-block:: shell ansible-playbook playbooks/preseed.yml -2. Install all servers using the generated preseed files. +5. Install all servers using the generated preseed files. -3. Invoke the ``bootstrap.yml`` playbook for every server, one by one. For +6. Invoke the ``bootstrap.yml`` playbook for every server, one by one. For example: .. code-block:: shell ansible-playbook -k -e server=ldap.example.com playbooks/bootstrap.yml -4. Finally, apply configuration on all servers: +7. Finally, apply configuration on all servers: .. code-block:: shell @@ -68,45 +92,6 @@ The playbooks and configurations for test site make a couple of assumptions: ``admin``. The SSH key stored in it will be read from location ``~/.ssh/id_rsa`` (i.e. from home directory of user running the Ansible commands). -* The TLS truststore can be found in location ``certs/example_ca_chain.crt`` - relative to the ``testsite`` sub-directory. - -Additionally, some manual steps may be required to have a fully functioning -system: - -* On ``ldap.example.com``, you should manually install the TLS private key and - certificate ing locations ``/etc/ssl/private/ldap.example.com.pem`` - (*root:ldap, 640*) and ``/etc/ssl/certs/ldap.example.com.pem`` (*root:root, - 644*), respectively. After that, re-run the ``site.yml`` playbook in order to - re-configure OpenLDAP server to use it. - -* On ``xmpp.example.com``: - - * Create TLS private key for XMPP in location - ``/etc/ssl/private/xmpp.example.com.pem`` (*root:prosody, 640*). - * Create TLS certificate for XMPP in location - ``/etc/ssl/certs/xmpp.example.com.pem`` (*root:root, 644*). - * After all files are in place, re-run the ``site.yml`` playbook in order to - restart necessary services etc. - -* On ``mail.example.com``, you should manually install the TLS private key and - certificate in locations ``/etc/ssl/private/mail.example.com.pem`` - (*root:ldap, 640*) and ``/etc/ssl/certs/mail.example.com.pem`` (*root:root, - 644*), respectively. After that, restart the servics ``dovecot`` and - ``postfix``. - -* On ``mail.example.com``: - - * Create TLS private key for SMTP in location - ``/etc/ssl/private/mail.example.com_smtp.pem`` (*root:openldap, 640*). - * Create TLS certificate for SMTP in location - ``/etc/ssl/certs/mail.example.com_smtp.pem`` (*root:root, 644*). - * Create TLS private key for IMAP in location - ``/etc/ssl/private/mail.example.com_imap.pem`` (*root:openldap, 640*). - * Create TLS certificate for IMAP in location - ``/etc/ssl/certs/mail.example.com_imap.pem`` (*root:root, 644*). - * After all files are in place, re-run the ``site.yml`` playbook in order to - restart necessary services etc. For more details on how the playbooks and configuration have been implemented, feel free to browse the test site files (in directory ``testsite``).