.. _ldap_client:

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.