From 8001cba3f69817e0a93b6c7c20504156973a5da6 2015-03-08 11:23:54
From: Branko Majic <branko@majic.rs>
Date: 2015-03-08 11:23:54
Subject: [PATCH] MAR-3: Added role documentation.

---

diff --git a/docs/rolereference.rst b/docs/rolereference.rst
index 4cb0879b30522cb0fa11258ac7ef310c26f4c509..3d358ae224a4b5a82c996f844b699a4e7c0f127c 100644
--- a/docs/rolereference.rst
+++ b/docs/rolereference.rst
@@ -279,6 +279,8 @@ packages on all servers:
     - debconf-utils
 
 
+.. _ldap_client:
+
 LDAP Client
 -----------
 
@@ -477,3 +479,85 @@ Here is an example configuration for setting-up LDAP server:
       uid: john
       cn: John Doe
       sn: Doe
+
+
+Prosody
+-------
+
+The ``prosody`` role can be used for setting-up Prosody, an XMPP server, on
+destination machine.
+
+The role implements the following:
+
+* Sets-up the Prosody apt repository.
+* Installs Prosody.
+* Configures Prosody.
+
+Prosody is configured as follows:
+
+* Modules enabled: roster, saslauth, tls, dialback, posix, private, vcard,
+  version, uptime, time, ping, pep, register, admin_adhoc, announce.
+* Self-registration is not allowed.
+* TLS is configured.
+* Client-to-server communication requires encryption (TLS).
+* Authentication is done via LDAP. For setting the LDAP TLS truststore, see
+  :ref:`LDAP Client <ldap_client>`.
+* Internal storage is used.
+* For each domain specified, a dedicated conference/multi-user chat (MUC)
+  service is set-up, with FQDN set to ``conference.DOMAIN``.
+* For each domain specified, a dedicated file proxy service will be set-up, with
+  FQDN set to ``proxy.DOMAIN``.
+
+
+Parameters
+~~~~~~~~~~
+
+**prosody_administrators** (list, mandatory)
+  List of Prosody users that should be granted administrator privileges over
+  Prosody. Each item is a string with value equal to XMPP user ID
+  (i.e. ``john.doe@example.com``).
+
+**prosody_tls_key** (string, mandatory)
+  Path to private key (on server itself) that should be used as server's private
+  key for TLS connections. The private key should correspond to certificate
+  listed in option ``prosody_tls_certificate``. The key file should be provided
+  in ``PEM`` format.
+
+**prosody_tls_certificate** (string, mandatory)
+  Path to *X.509* certificate (on server itself) that should be used as server
+  certificate for TLS connections. The certificate file should be provided in
+  ``PEM`` format.
+
+**prosody_domains** (list, mandatory)
+  List of domains that are served by this Prosody instance. Each item is a
+  string specifying a domain.
+
+**prosody_ldap_server** (string, mandatory)
+  Fully qualified domain name, hostname, or IP address of the LDAP server used
+  for user authentication and listing.
+
+**prosody_ldap_bind_dn** (string, mandatory)
+  Distinguished name of LDAP user used for authenticating to the LDAP
+  server. This user is used for looking-up the users available on the
+  server. Users themselves authenticate via their own account.
+
+**prosody_ldap_password** (string, mandatory)
+  Password used for authenticating to the LDAP server.
+
+**prosody_ldap_filter** (string, mandatory)
+  LDAP filter used for obtaining a list of users available on the Prosody
+  server. Two special strings can be used for specifying the user and domain,
+  ``$user``, and ``$host`` within. These will be replaced with real values in
+  the filter every time a user is looked-up.
+
+**prosody_ldap_scope** (string, mandatory)
+  Scope for performing the LDAP search for obtaining a list of users available
+  on the Prosody server.
+
+**prosody_ldap_tls** (boolean, mandatory)
+  Specifies whether to use STARTTLS extension when connecting to the LDAP server
+  or not.
+
+**prosody_ldap_base** (string, mandatory)
+  Base DN under which the lists of users available on the Prosody should be
+  looked-up.