====== XMPP Server Configuration ======

AstLinux includes the [[http://prosody.im|Prosody]] [[wp>XMPP|XMPP (Jabber)]] server for secure Instant Messaging and Group Chats on AstLinux itself, no external provider or service is required.

In addition to providing XMPP services for local and remote clients, (iOS, Android, desktop PC's, etc.), Asterisk can be an XMPP client offering additional benefits.  (See Notes below)

!!Note: AstLinux 1.1.0 or later is required!!

==== General Configuration ====

The AstLinux Web Interface is used for configuration, click on **Configure XMPP**\\

Network tab -> Network Services:\\
{{:userdoc:xmpp-network-tab.png?nolink|Configure XMPP}}

The XMPP server requires secure SSL/TLS connections, as such it requires a certificate.  For convenience by default, the XMPP server shares the Asterisk SIP-TLS Server Certificate.  If you already created one, you are good and can skip the next step, if not you will see the following entry:

{{:userdoc:xmpp-missing-cert.png?nolink|Missing SIP-TLS Server Certificate}}

Click **SIP-TLS Certificate**, use a Key Size of 2048 Bits and set the "Server Cert DNS Name" to the host.domain of your AstLinux box.  When completed, navigate back to the **XMPP Server Configuration** screen and the previous "Missing SIP-TLS..." section should no longer be displayed.

Continuing, the basic default settings are as follows, the Hostname should usually be filled in to match your Network Tab settings.

{{:userdoc:userdoc-xmpp-defaults2.jpg?nolink|XMPP Basic Configuration}}

Before we can add users the XMPP Server must be "enabled", **Save Settings**, then **Restart Server**.  You will now see a "Client Credentials" section.

{{:userdoc:xmpp-client-credentials.jpg?nolink|Client Credentials}}

Next, create users using JID's (in the format ''user@host.domain''), **Save Settings**.

!!Tip ->!! If only client credentials are added, deleted or passwords changed, the XMPP server does **not** need to be restarted for only client credential changes.

Now you can connect to AstLinux with any standard [[wp>Comparison_of_instant_messaging_clients|XMPP client]].

!!Tip ->!! If you already use [[http://www.counterpath.com/bria-iphone-edition.html|Bria]] as a SIP softphone app on the iPhone/Android phone, you can add "IM (Presence and Messaging)" as an In-app Purchase. It works very well together with AstLinux's XMPP server, Prosody.

!!Tip ->!! Be sure to specify a Resource: value in your XMPP client, the value does not matter, but clients such as Bria will use a changing UUID when the Resource: field is empty.  A non-consistant Resource: value will cause problems.

==== Admin User ====

An "Admin User" is not needed necessarily. An "Admin User" can do certain administrative tasks from some XMPP clients (which use Ad-hoc commands) like Pidgin or Adium, like adding users or getting a list of online users and a lot more. Most can be done from the Web Interface. Be careful when you open the XMPP server to the internet (e.g. for mobile clients).  Do not define the "Admin User" unless it is required for your solution.

==== Multi-User Chat (MUC) ====

Optionally, to enable Multi-User/Group Chat functionality, you need to add something like "conference.host.domain" to the Multi-User Chat Conference field and restart XMPP Server.

{{:userdoc:xmpp-chat-conference.jpg?nolink|Multi-User Chat Conference}}

Now you can create a new room (e.g "chat") on the fly, if you connect your XMPP client to e.g. "chat@conference.host.example.com", you can invite other Buddies to this room as well.  Featured XMPP clients, which can use Ad-hoc commands, can use "''/config''" to set some options for the chat room.

==== PubSub Service ====

!!Note: AstLinux 1.1.3 or later is required!!

Optionally, to enable PubSub functionality, you need to add something like "pubsub.host.domain" to the PubSub Service field and restart XMPP Server.

{{:userdoc:xmpp-pubsub.jpg?nolink|PubSub Service}}

!!Tip ->!! See Also: **[[tt_distribute_events_xmpp_pubsub|Distribute Asterisk Events using XMPP PubSub]]**
==== Server-to-Server connections ====

In order to forward XMPP requests that can not be handled locally, you just need to enable "Server-to-Server" (and open TCP port 5269 in your firewall from every other allowed XMPP server). When you add a contact/buddy from another server via an XMPP client, the server-to-server connection will be established to forward the request to the proper server. The clients initiate the connections on TCP port 5222, you should also configure in your firewall for which clients are allowed.

==== DNS Configuration ====

DNS plays an important role with XMPP routing.  [[http://prosody.im/doc/dns|DNS configuration in XMPP]]\\
To keep things simple just use JID's that match the ''user@host.domain'' format, where the DNS of your box is ''host.domain'' .  Though, it is often desired to keep the JID's more compact, ie. ''user@domain'' format.  In that case you need DNS SRV records to map XMPP ''@domain'' requests to the ''host.domain'' server.  Also keep in mind that mobile devices may appear on both the public and private side of AstLinux, so both public DNS and AstLinux's local DNS must be configured properly.

For example, with XMPP clients using AstLinux's DNS, let's assume ''sip-tls.example.com'' points to Asterisk both locally and publicly, which is also our XMPP server.  Using the Web Interface:\\
**Network -> Advanced Configuration: -> Edit DNSMasq Static**

  srv-host=_xmpp-client._tcp.example.com,sip-tls.example.com,5222

will define a DNS SRV record pointing ''@example.com'' JID's to ''sip-tls.example.com'' using TCP port 5222 .

Public DNS SRV records will have to be defined outside of AstLinux.

==== Shared Groups ===

Groups were designed to allow administrators to create virtual groups of users that automatically see each other in their contact lists. The shared groups will be sent to the user along with their usual roster without overriding or permanently adding the contacts. There is no need for the user to authorise the these contacts in their contact list - this is done automatically on the server (be careful: everyone in a group can monitor the presence of each other!).

As an example, if you have a team of people working together on a project, you can create a group for that team. They will automatically be added to each others' contact lists, and the list can easily be modified on the server at any time to add and remove people.

{{:userdoc:xmpp-shared-groups.png?nolink|Shared Groups}}

The file in AstLinux lives in ''/mnt/kd/prosody/sharedgroups.conf''

Example:
<code>[Support Team]
support@example.com
john.doe@example.com

[Development Team]
hardworkingdeveloper@example.net=Joe Coder
other.dev@example.com=Mel
</code>

You can see the last two entries have custom names, if no name is given then it is up to the user's client to find a suitable name (e.g. take it from the contact's vcard/profile).

The shared groups file can be reloaded from the Web Interface without restarting the XMPP Server.

==== Miscellaneous ====

If you need more options than AstLinux offers in the Web Interface (plus some additional variables in "rc.conf"), you can (as usual) create your own Prosody specific "''/mnt/kd/prosody/prosody.conf''" configuration file, which then has priority.  Though this practice is discouraged since if "''/mnt/kd/prosody/prosody.conf''" exists some of the entries of the Web Interface XMPP Configuration will be ignored.

==== XMPP Command Line Client ====

!!Note: AstLinux 1.1.1 or later is required!!

For use in custom shell scripts or as an alternative to the XMPP/Jabber implementation in Asterisk (see note below) you can use the "''sendxmpp''" CLI XMPP client to send XMPP messages or get the XMPP status of Buddies from within the Asterisk dialplan via the "''System''" application or the "''SHELL''" function. This can be very useful in combination with the new SQL database functions (to get the specific JID).

Examples:

  ; Sends message to a buddy (like "JabberSend")
  same => n,System(sendxmpp -t ${JID} -m 'Call from Alice')

  ; Gets online status of a buddy (like "JABBER_STATUS")  
  same => n,Set(str=${SHELL(sendxmpp -c presence -t ${JID})})
  same => n,Set(status_num=${CUT(str,~,1)})

!!Note ->!! The sendxmpp client JID needs to be a buddy (or in a shared group) to send a message to another client.

For more information, from the CLI type:
  sendxmpp --help

Example ''/mnt/kd/clix.conf'' configuration file used by ''sendxmpp'':

  [default]
  jid=user@example.com
  password=secret

==== Notes: ====

  * Depending on your setup you may need to open the related TCP port(s) on your firewall, to allow clients/servers to connect.

  * Asterisk 1.4 + 1.8 (res_jabber) and !!AstLinux 1.1.0->1.1.2!! do not work as an XMPP/Jabber client with Prosody, they crash instantaneously, Asterisk 11 works fine, it has a new XMPP implementation.  Fortunately, !!AstLinux 1.1.3 or later!! works with both Asterisk 1.8 (res_jabber) and Asterisk 11 (res_xmpp).