XMPP Server Configuration

AstLinux includes the Prosody 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

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

Network tab → Network Services:

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:

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.

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

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 XMPP client.

Tip -> If you already use 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.

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.

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.

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.

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.

Tip -> See Also: Distribute Asterisk Events using XMPP PubSub

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 plays an important role with XMPP routing. 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.

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.

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

Example:

[Support Team]
support@example.com
john.doe@example.com

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

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.

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.

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

• 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).