Ejabberd comes with various default settings that make it easy to get started. We can install Ejabberd and start using it as soon as installation completes. This works when we are testing our setup, but when we need a production server, we need to make a number of changes to the default installation. Ejabberd provides a central configuration file through which we can easily configure our XMPP installation.
This recipe covers the basic configuration of the Ejabberd server.
Getting ready
Make sure that you have installed the Ejabberd server.
You will need access to a root account or an account with sudo privileges.
How to do it…
Ejabberd configuration files are located under the conf directory in the Ejabberd installation. On the Ubuntu server, it should be /opt/ejabberd-version/conf.
Follow these steps to configure the Ejabberd installation:
Open the ejabberd.yml file. It contains configuration settings in the YML format.
Let us start by setting the domain for our XMPP service. This is located under the SERVED HOSTNAMES section in the configuration file. The default setting uses the server hostname as a host for the XMPP service.
Add a fully qualified domain name under the hosts section. You can choose to keep the default host entry or remove it:
Next, you may want to change the default ports for XMPP connections. Search for the LISTENING PORTS section in ejabberd.yml and change the respective ports. I will use the default port configuration. The following is the configuration snippet listing port 5222:
The LISTENING PORTS section contains different port configurations, each serving a separate service. Three of them are enabled by default and serve a client to server connection (5222), server to server connection (5269), and HTTP module for admin console and http_bind service (5280).
The same section contains the parameter named certfile, which specifies the SSL certificate file to be used while creating client connections. The default settings point to a certificate created by the Ejabberd installation process. You can change it to your own signed certificate.
Also note the shaper and access settings. These settings specify the connection throttling and access control settings used for the client to server connections respectively.
At the end of the LISTENING PORTS section, there is a configuration for BOSH (port 5280) connections, as well as the web admin panel. This section also enables web socket connections with the ejabberd_http_ws module.
Under the AUTHENTICATION section, you can configure the authentication mechanism to be used. By default, Ejabberd uses internal authentication but it can be set to use external scripts, system-level authentication, external databases, or even a centralized LDAP service. The following is the list of all supported options:
Default internal authentication works well enough and we will proceed with it. If you are planning to use a different authentication mechanism, make sure that you comment out internal authentication.
You can also enable anonymous login support, where clients can open an XMPP connection without a username and password. Simply uncomment the respective settings from Anonymous login support:
Next, under the DATABASE SETUP section, you can set Ejabberd to use an external database system. Ejabberd supports all leading relational database systems, including SQLite. The following is the list of all supported database systems:
The default database settings use an inbuilt database server known as Mnesia. It provides in-memory and disk-based storage and can be easily replicated across Ejaberd nodes. Mnesia works well even for very busy XMPP operations.
To define an admin user, search for the ACCESS CONTROL LISTS section and add your desired username and hostname under the admin users list:
This same section includes a list of blocked users.
You can also define your own access control lists, which can be used to restrict permissions to specific hostnames or users. The Access Rules section define the rules applicable to listed ACLs.
Finally, under the modules section, you can configure the modules to be used by Ejabberd. Modules are plugins to extend the functionality of the Ejabberd server. Comment out the modules that you are not planning to use. You can also enable or disable any module in runtime from the web admin panel. The following is the partial list of modules:
Each module is named after respective XEPs (XMPP extensions). You can get details of the functionality of any module by looking for the related XEP. Also check the Ejabberd documentation to find out the dependencies between modules.
Once you are done with all the configuration, you can restart the Ejabberd server with ejabberdctl restart or reload configuration changes with the ejabberdctl reload_config command:
$ sudo bin/ejabberdctl reload_config
How it works…
Most of the core settings of Ejabberd are controlled through the configuration file, ejabberd.yml. Alternatively, you can change settings with the ejabberdctl command, but those settings will not persist after restart. If you need the settings to be permanent, change them in the configuration file. You can always reload the configuration file changes without restarting the server.
While editing the configuration file, make sure that you follow the indentation and spacing as shown in examples. Ejabberd configuration follows the YML format and any change in spacing will leave that setting undefined. The good news is that the latest version of Ejabberd will prompt you about any mistakes in configuration.
There's another file named ejabberdctl.cfg that contains Erlang runtime settings. You may need to update those parameters while performance tuning the Ejabberd server.
Strophe is a collection of libraries that can be used to communicate with the XMPP server. It contains libstrophe, which is a C-based implementation of XMPP client functionalities, and Strophe.js, which is a JavaScript implementation. Strophe provides core XMPP client functionality and can be extended with custom modules. The community has contributed various extensions to support additional XMPP functions.
With a limit on page count, I will focus on a simple demo of Strophe.js where we download the code and modify an example to connect with our XMPP server.
Getting ready
You will need the XMPP server installed and running. You can also use public XMPP servers, but make sure that you register with them and obtain your username (JID) and password.
You will need at least two user accounts to communicate with each other.
As we are using a web-based connection, it needs a Bidirectional-streams Over Synchronous HTTP (BOSH) extension enabled on the XMPP server. Ejabberd supports this functionality with mod_http_bind and it should be enabled by default.
Download and extract the latest source achieve from the Strophe.js site: http://strophe.im/strophejs/ .
Optionally, you will need a web server set up to access a web client.
How to do it…
I assume the source code is located in the StropheJS directory. We will use one of the examples shipped with the StropheJS source:
Change the directory to examples under the extracted StropheJS code. This directory contains multiple examples, demonstrating different features of StropheJS. We will use echobot.js and echobot.html as our starting point.
Open echobot.js and change the BOSH_SERVICE URL on the first line, as follows:
var BOSH_SERVICE = 'http://hostname:5280/http-bind';
Replace the hostname with your XMPP domain or XMPP server IP address. For example, if your XMPP server is available at xmpp.mysrv.com, then the BOSH_SERVICE URL will be as follows:
var BOSH_SERVICE = 'http://xmpp.mysrv.com:5280/http-bind';
Optionally, you can enable debug logging to watch actual data exchanged between client and server. Find the $(document).ready() section and uncomment the following lines:
// uncomment the following lines to spy on the wire traffic.
connection.rawInput = function (data) { log('RECV: ' + data); };
connection.rawOutput = function (data) { log('SEND: ' + data); };
Save the changes to echobot.js and open echobot.html in your browser. You should see a page with two text fields, one for JID and another for Password:
Enter your JID (XMPP username) and respective password and click connect.
Now, Strophe.js will try to open an XMPP connection and log in with the given details. If the connection is successful, you should see the following screen:
The last line includes your JID, with a unique identifier for the current session appended at the end. This form of JID is also called full JID.
Open a separate client connection with, say, PSI, log in with some other user, and send a message on your given JID. This should print your message on the web page and the same message will be echoed back to the sender. Your web page should look similar to the following screenshot:
How it works…
Strophe.js is a JavaScript-based XMPP client library that makes it easy to write your own web-based XMPP clients. Strophe handles all actual communication parts, such as the encoding and decoding of XML stanzas, the connection procedure, and so on. You can use simple APIs provided by Strophe to create your client. Strophe.js uses jQuery to work with the HTML DOM, so if you are familiar with jQuery you will feel at home when working with Strophe.
If you browse through the code in echobot.js, you will see two main event handlers: onConnect and onMessage. These event handlers are attached to specific events and are executed when that event occurs. The onConnect handler is attached to a connection object to capture any change in connection state, and onMessage is attached as a handler for message events. It will be triggered when our client receives any message from the server.
If you are interested in the syntax for the addHandler function, it is as follows:
addHandler: function (handler,ns,name,type,id,from,options)
The handler parameter is the actual function to manipulate an incoming message object; ns is the XMPP namespace and can be used to receive packets only from a certain namespace. It defaults to jabber:client, the name parameter, which is the name of an element to act upon—in our case, it is message. You can use iq or presence to receive respective data types. Other parameters add more filtering options, where you can specify a specific ID for the message, type of the message packet (chat or normal or group, defaults to chat) and other options.
The handler function onMessage gets triggered whenever a connection object receives a new message from the server. Then, it parses the received data and extracts all required information. As it is an echo bot, it simply reads the message and echoes it back to the sender. The new message packet is generated with the following lines:
var reply = $msg({to: from, from: to, type: 'chat'})
.cnode(Strophe.copyElement(body));
The message is passed to a connection object with the following lines, which in turn sends it to the server:
connection.send(reply.tree());
The last section initiates the Strophe client on page load (ready). When we click on the connect button, a click handler in this section gets triggered and opens a new connection with the XMPP server. The same button is changed to disconnect so that we can send a proper disconnect request to the server.
There's more…
Strophe.js supports WebSocket-based XMPP connections, and the latest version of Ejabberd has also added support for WebSockets. WebSockets provides noticeable performance improvements and reduces connection time over BOSH connections. In the preceding example, we have used the BOSH protocol, which can be replaced with WebSocket simply by changing the BOSH_SERVICE URL as follows:
var BOSH_SERVICE = 'ws:// hostname:5280/websocket';
If you need a secure WebSocket connection, use the wss protocol instead of:
wsvar BOSH_SERVICE = 'wss:// hostname:5280/websocket';
You should check other examples, mainly prebind and restore. Both demonstrate connection features that can help in reducing connection delay.
See also
StropheJS official page at http://strophe.im/strophejs/
StropheJS GitHub repo at https://github.com/strophe/strophejs
StropheJS API documentation at http://strophe.im/strophejs/doc/1.1.3/files/strophe-js.html
StropheJS plugins at https://github.com/metajack/strophejs-plugins
