From 0969ee81219aff3fcb59eeba8e7d2630ddaac46f 2015-10-25 18:28:43 From: Branko Majic Date: 2015-10-25 18:28:43 Subject: [PATCH] MAR-18: Added usage instructions for the LDAP server/client roles. --- diff --git a/docs/usage.rst b/docs/usage.rst index 07e99a308e4db15e98af9e665059c51a48df713c..5bb985c429b0fc608b19fb557e085abd0056f19d 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -391,3 +391,159 @@ Let's take care of this common configuration right away: 6. After this you should be able to ssh using the user ``admin`` via public key. The ``admin`` user's password has also been set to ``admin``, and the user will be member of ``sudo`` group. + + +Introducing LDAP +---------------- + +Since some of the services actually depend on LDAP, we'll go ahead and set that +one up first. This includes both the LDAP *server* and *client* configuration. + +1. Update the playbook for communications server to include the LDAP client and + server roles (``ldap_client`` and ``ldap_server``, respectively). + + :file:`~/mysite/playbooks/communications.yml`:: + + --- + - hosts: communications + remote_user: ansible + sudo: yes + roles: + - common + - ldap_client + - ldap_server + +2. Update the playbook for web server to include the LDAP client role + (``ldap_client``). You never know when it might come in handy :) + + :file:`~/mysite/playbooks/web.yml`:: + + --- + - hosts: web + remote_user: ansible + sudo: yes + roles: + - common + - ldap_client + +3. Time to configure the roles. For start, let us configure the LDAP server + role. Keep in mind that there is a lot of default variables set-up by the + role itself, making our config rather super-short. + + :file:`~/mysite/group_vars/communications.yml`:: + + --- + + ldap_admin_password: admin + ldap_server_organization: "Example Inc." + +4. Phew. That was... Well, actually, easy :) Technically, only the LDAP admin + password *must* be set, but it's nice to have better organisation specified + than the default one. Let's add the LDAP client configuration next. We will + start off with global LDAP client configuration. In case of LDAP client, + we've got to be a bit more explicit. + + :file:`~/mysite/group_vars/all.yml`:: + + # Take note how we set the base DN. By default the ldap_server role + # (defined up there) will use server's domain to form the base for LDAP. + ldap_client_config: + - comment: Set the base DN + option: BASE + value: dc=example,dc=com + - comment: Set the default URI + option: URI + value: ldap://comms.example.com/ + - comment: Set the LDAP TLS truststore + option: TLS_CACERT + value: /etc/ssl/certs/ca.pem + - comment: Enforce TLS + option: TLS_REQCERT + value: demand + +5. Ok, so this looks nice and dandy... But, let's have a bit better + configuration on the communications server itself. Namely, on that one we + should be able to connect to socket with LDAP clients instead over TCP port. + + :file:`~/mysite/group_vars/communications.yml`:: + + ldap_client_config: + - comment: Set the base DN + option: BASE + value: dc=example,dc=com + - comment: Set the default URI + option: URI + value: ldapi:/// + - comment: Set the default bind DN, useful for administration. + option: BINDDN + value: cn=admin,dc=example,dc=com + - comment: Set the LDAP TLS truststore + option: TLS_CACERT + value: /etc/ssl/certs/ca.pem + - comment: Enforce TLS + option: TLS_REQCERT + value: demand + +6. Ok, time to re-run the playbooks again... Wait a minute, something is missing + here... Oh, right, forgot to mention one thing - Majic Ansible Roles use TLS + throughout wherever possible. In other words, you *must* have TLS private + keys and certificates issued by some CA for all servers in order to be able + to use most of the roles (actually, you need them issued per *service*). This + includes ``ldap_server`` too. So, let's make a slight detour to create a CA + of our own, plus the necessary server certificate for the LDAP service... + + 1. Let's first install a couple of more tools on the Ansible server, since we + will be using ``certtool`` for our improvised CA needs:: + + apt-get install gnutls-bin + + 2. Create directory where the private keys and certificates will be stored + at:: + + mkdir ~/mysite/tls/ + + 3. It is time to create a couple of templates for the ``certtool`` so it + would know what extensions and content to have in the certificates: + + :file:`~/mysite/tls/ca.cfg`:: + + organization = "Example Inc." + country = "SE" + cn = "Example Inc. Test Site CA" + expiration_days = 1825 + ca + cert_signing_key + crl_signing_key + + :file:`~/mysite/tls/comms.example.com_ldap.cfg`:: + + organization = "Example Inc." + country = SE + cn = "Exampe Inc. LDAP Server" + expiration_days = 365 + dns_name = "comms.example.com" + tls_www_server + signing_key + encryption_key + + 4. Almost there... Now let's generate the keys and certificates:: + + 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 + certtool --sec-param normal --generate-privkey --outfile ~/mysite/tls/comms.example.com_ldap.key + certtool --generate-certificate --load-ca-privkey ~/mysite/tls/ca.key --load-ca-certificate ~/mysite/tls/ca.pem --template ~/mysite/tls/comms.example.com_ldap.cfg --load-privkey ~/mysite/tls/comms.example.com_ldap.key --outfile ~/mysite/tls/comms.example.com_ldap.pem + +7. With private keys and certificates in place, we are almost ready to re-run + the playbooks! Now, just a *small* tweak to the general configuration, and + all should be fine. + + :file:`~/mysite/group_vars/all.yml`:: + + tls_private_key_dir: "~/mysite/tls/" + tls_certificate_dir: "~/mysite/tls/" + ca_certificates: + - "~/mysite/tls/ca.pem" + +8. And now as finishing touch, simply run the playbooks again:: + + ansible-playbook playbooks/site.yml