Adding XMPP server

------------------

Now that the users can communicate via mail server, we might as well add support

for some instant messaging. For this purpose, we will use the ``xmpp_server``

role.

1. Update the playbook for communications server to include the XMPP server

   role.

   :file:`~/mysite/playbooks/communications.yml`::

      ---

      - hosts: communications

        remote_user: ansible

        sudo: yes

        roles:

          - common

          - ldap_client

          - ldap_server

          - mail_server

          - xmpp_server

2. Configure the role.

   :file:`~/mysite/group_vars/communications.yml`::

      # Set one of the users to also be an XMPP administrator.

      xmpp_administrators:

         - john.doe@example.com

      # Unfortunately, XMPP can't look-up domains via LDAP, so we need to be

      # explicit here.

      xmpp_domains:

         - example.com

      # Simply point the XMPP server to base DN of LDAP server, and let it use

      # specific directory structure it expects.

      xmpp_ldap_base_dn: dc=example,dc=com

      # Password for logging-in into the LDAP directory.

      xmpp_ldap_password: prosody

      # Where the LDAP server is located at. Full-blown LDAP URIs are _not_

      # supported!

      xmpp_ldap_server: comms.example.com

3. Now, like in case of the mail server role, we need to set-up authentication

   for the XMPP service. In this particular case a single consumer is present -

   Prosody itself. We should also create the group for granting the users right

   to use the service.

   :file:`~/mysite/group_vars/communications.yml`::

      # Just make sure the new entry is added for the prosody user - you can

      # leave the postfix/dovecot intact in your file if you use different

      # passwords. Keep in mind password for prosody user must match with

      # password specified under xmpp_ldap_password.

      ldap_server_consumers:

         - name: postfix

           password: postfix

         - name: dovecot

           password: dovecot

         - name: prosody

           password: prosody

      # And simply append a new group here...

      ldap_server_groups:

         - name: mail

         - name: xmpp

4. Ok, configuration of the role is almost complete. You may have noticed that

   we still haven't added any users to the new LDAP group called "xmpp". So let

   us correct this in similar way as we did for the mail server. Since we have

   the user entries already, no need to recreate them here. We will just update

   the group membership instead.

   .. warning::

      Same warning applies here as for mail server role for managing the

      user/group entries! Scroll up and re-read it if you missed it!

   :file:`~/mysite/group_vars/communications.yml`::

      # Don't replace the entire ldap_entries, just append the new group

      # modification.

      ldap_entries:

          # Add the two users to the xmpp group. Observe that we use

          # the "state: append" option. This is a bit of a cheat since the

          # ldap_entries option passes the provided entries directly to the

          # ldap_entry module. "state: append" will make sure we don't overwrite

          # the group, and instead add the attributes to it (in this case we add

          # the two users).

          - dn: cn=xmpp,ou=groups,dc=example,dc=com

            uniqueMember:

              - uid=johndoe,ou=people,dc=example,dc=com

              - uid=janedoe,ou=people,dc=example,dc=com

            state: append

5. Do you know what it is time to do now? Yes! Create some more TLS private keys

   and certificates, this time for our XMPP server ;)

   1. Create new template for ``certtool``:

      :file:`~/mysite/tls/comms.example.com_xmpp.cfg`::

         organization = "Example Inc."

         country = SE

         cn = "Exampe Inc. XMPP Server"

         expiration_days = 365

         dns_name = "comms.example.com"

         tls_www_server

         signing_key

         encryption_key

   2. Create the keys and certificates for XMPP service based on the template::

        certtool --sec-param normal --generate-privkey --outfile ~/mysite/tls/comms.example.com_xmpp.key

        certtool --generate-certificate --load-ca-privkey ~/mysite/tls/ca.key --load-ca-certificate ~/mysite/tls/ca.pem --template ~/mysite/tls/comms.example.com_xmpp.cfg --load-privkey ~/mysite/tls/comms.example.com_xmpp.key --outfile ~/mysite/tls/comms.example.com_xmpp.pem

6. Apply the changes::

     ansible-playbook playbooks/site.yml

7. If no errors have been reported, at this point you should have two users

   capable of using the XMPP service - one with username

   ``john.doe@example.com`` and one with username ``jane.doe@example.com``. Same

   passwords are used as for when you were creating the two users for mail

   server. For testing you can turn to your favourite XMPP client (I don't know

   of any CLI-based tools to test the XMPP server functionality, unfortunately).