diff --git a/docs/testsite.rst b/docs/testsite.rst index a9ddf29718e7345d91688a1534cfb52845f70132..1f87bd8fd1d648ddba4cc1c0b85cdc513b620e9d 100644 --- a/docs/testsite.rst +++ b/docs/testsite.rst @@ -29,6 +29,9 @@ bootstrap.yml (for bootstrapping fresh nodes) ldap.yml This playbook sets-up the LDAP servers. It is included in ``site.yml``. +mail.yml + This playbook sets-up the mail server. It is included in ``site.yml``. + preseed.yml This playbook sets-up the Debian preseed files. It is included in ``site.yml``. @@ -36,16 +39,46 @@ preseed.yml site.yml This playbook sets-up all servers, including preseed files on local host. +web.yml + This playbook sets-up the web server. It is included in ``site.yml``. + +xmpp.yml + This playbook sets-up the XMPP server. It is included in ``site.yml``. + In order to deploy the test site, the following steps would normally be taken: -1. Create TLS private keys (relative to top level directory): +1. If you do not wish to have the hassle of creating the private keys and + issuing certificates, run the following commands to get this done for you + automatically, and skip to step 5 (otherwise follow steps 2 through 4): + + .. code-block:: shell + + certtool --sec-param high --generate-privkey --outfile tls/example_ca.key + certtool --template tls/templates/example_ca.cfg --generate-self-signed --load-privkey tls/example_ca.key --outfile tls/example_ca.pem + cp tls/example_ca.pem tls/example_ca_chain.pem + for template in tls/templates/*.cfg; do + entity_basename="$(basename "$template" .cfg)" + [[ $entity_basename == example_ca ]] && continue + certtool --sec-param normal --generate-privkey --outfile "tls/$entity_basename.key" + certtool --generate-certificate \ + --load-ca-privkey "tls/example_ca.key" \ + --load-ca-certificate "tls/example_ca.pem" \ + --template "$template" \ + --load-privkey "tls/${entity_basename}.key" \ + --outfile "tls/${entity_basename}.pem" + done + +2. 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`` + - ``testsite/tls/web.example.com_https.key`` + - ``testsite/tls/phpfino.example.com_https.key`` + - ``testsite/tls/wsgi.example.com_https.key`` -2. Issue TLS certificates corresponding to the generated TLS private keys (make +3. 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 @@ -56,36 +89,44 @@ In order to deploy the test site, the following steps would normally be taken: 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 + - ``testsite/tls/web.example.com_https.pem`` (subject alternative name should + be ``web.example.com``) + - ``testsite/tls/web.example.com_https.pem`` (subject alternative name should + be ``web.example.com``) + - ``testsite/tls/phpinffo.example.com_https.pem`` (subject alternative name + should be ``phpinfo.example.com``) + - ``testsite/tls/wsgi.example.com_https.pem`` (subject alternative name + should be ``wsgi.example.com``) + +4. 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.pem``. It is very important to include the CA chain used for LDAP server. -4. Generate the preseed files: +5. Generate the preseed files: .. code-block:: shell ansible-playbook playbooks/preseed.yml -5. Install all servers using the generated preseed files. +6. Install all servers using the generated preseed files. -6. Add the SSH host fingerprints to your ``known_hosts`` file (don't forget to +7. Add the SSH host fingerprints to your ``known_hosts`` file (don't forget to remove old entries if you are redoing the process). You can easily obtain all the necessary fingerprints with command: .. code-block:: shell - ssh-keyscan mail.example.com ldap.example.com xmpp.example.com + ssh-keyscan mail.example.com ldap.example.com xmpp.example.com web.example.com -7. Invoke the ``bootstrap.yml`` playbook in order to set-up some basic +8. Invoke the ``bootstrap.yml`` playbook in order to set-up some basic environment for Ansible runs on all servers: .. code-block:: shell ansible-playbook playbooks/bootstrap.yml -8. Finally, apply configuration on all servers: +9. Finally, apply configuration on all servers: .. code-block:: shell