XMPP is an open source protocol for instant messaging, audio and video conferencing and data exchange. It is superior to solutions like WhatsApp, Skype or Facetime because it is decentralized and it allows encryption and authentication based on trusted and tested open source standards instead of some proprietary mumbo-jumbo. The only two things you need to communicate over XMPP is a client software and an account on some XMPP server. Both can be found for free in dozens – if not hundreds – on the internet.

One disadvantage though is the fact that free servers often suffer from outages or are suddenly discontinued, as was recently announced for the popular jitsi xmpp server. The good news is that it is not so difficult to set up your own xmpp server which you can fully control. Here’s how…

Building Prosody

Prosody is a lightweight and simple to configure xmpp server, which is exactly what we need. You could basically install it with a one-liner by issuing

One drawback of this method is that it might fail to integrate the most recent bug fixes and patches. When I first tried this method, I got an installation which lacked a patch for a malfunction in the init script. When I ran my own build from the 15.05.1 package sources the bug was cleanly patched.

LuaDBI as custom package

If we want to use our MySQL database to store user account information, we need the (MySQL flavored) luadbi module. As this module is not included in the default oWRT package feeds, we have to provide it ourselves. Fortunately, someone else has already done my work. There is a pretty recent Makefile on Nathaniel W. Filardo’s github page. All we have to do is to add this to our custom packages:

Strangely enough, there is no way to trigger an installation of the single luadbi package, so we just install them all. We can now M-select luadbi-common and luadbi-mysql in menuconfig. After that, save the menuconfig settings and launch the package compile.

Compile prosody

Compiling prosody is a piece of cake: Just M-Select prosody im menuconfig, save and trigger a compile run from your console:

After that scp all packages to your router and do a local opkg install (do not forget the luadbi package you previously produced.)

Configuration of the server

There is a very useful configuration walk-through for setting up Prosody on a Raspberry on YouTube. Most settings just involve commenting in/out using the lua comment string which is — . The settings in /etc/prosody/prosody.cfg.lua should should be set as follows:

Setting the correct hostname

The first step is to replace all occurences of example.com by your hostname (in our case hobbykeller.spdns.de):

Remote administration

If remote administration from the XMPP client is not urgently required, the safest setting is to leave the admin section and later disable admin_adhoc.

With the admin_adhoc functionality switched off, all admin operations are done on the server console using the prosodyctl command. The only disadvantage is that you probablby need the admin account to send out an “all stations” message such as announcing a downtime of the server or similar. This might only be possible from an admin account with admin_adhoc enabled.

Settings for other modules

legacyauth has been commented out by me because imho the use of old clients should not be encouraged for security reasons. Outdated clients often lack essential security patches and therefore offer a attack vectors to potential hackers.

admin_adhoc has also been commented out to reduce the number of potential attack vectors (see above).

watchonlineregistrations is not needed either if there is no xmpp admin account anyway.

allow_registration is a tricky thing. On the one hand, it does not seem to be a good idea to offer any kind of administrative tasks (including the creation of new user accounts) to the public. On the other hand, it is most comfortable if users – which you personally invited before – can set their own logins and passwords. One way is to initially set allow_registration = true and set it back to false an reload the server settings once all users are registered.

authentication – It is best practice to always store passwords in a hashed format and not in plain text in order to make life more difficult for people who try to hack into servers and steal identity information. Therefore we change the default plain text setting to authentication = internal_hashed

SQL settings

As we are running a MySQL server anyway, there are plenty of reasons not to store user data in flat files but inside the MySQL database. One such reason is that in case of a system migration, all prosody user account data is automatically migrated once the database has been migrated.

This won’t be enough though, we also have to add the MySQL parameters:

As in the case of setting up WordPress and ownCloud previously, it is extremly important not to use localhost for the host parameter but 127.0.0.1 otherwise database operations triggered by prosodyctl will fail with some cryptic error message.

Make sure, that the MySQL server …

• has a user prosody set up with the corresponding password
• already has an (empty) database with the name prosody installed
• that the user has sufficient access privileges on that database.

Firewall settings: Port forwarding

As usual when running servers the correct firewall settings are of crucial importance. Prosody needs ports 5222 and 5269 forwarded (for legacy authentication port 5223 might be additionally opened).

Main router (Fritzbox, homebox,…)

As the ports must evidently be opened on the main router which connects to the wan, open the ports mentioned above on the main device. Protocol is tcp an target is the IP address of your OpenWRT router which operates behind the home box.

This is the default production scenario. Your oWRT router is cable connected to the homebox and acts as an access point for wireless and ethernet clients. At the same time it runs all necesseray servers:

In this scenario it is enough to just open the ports on your oWRT machine:

In sta mode operation

This scenario usually concerns routers which operate in testing mode before becoming production routers. They connect as a wireless TESTING client to an existing oWRT router they will later replace.

If your router operates as such a wireless client to the OpenWRT router behind the homebox, you must set forwarding rules both on the oWRT router behind the homebox and on your oWRT sta device (hereby called “sta-router”).

Accepting traffic on the sta-router

This is the router you are actually working on and setting up the prosody server on. It is sufficient here to just add an ACCEPT rule:

Keep in mind that on the TESTING router, the src network is not called wan but wwan in order to emphasize the wireless way, the testing router connects to the homebox as opposed to the ethernet connection by which the main production router is connected to the homebox.

Forwarding traffic to the production router

In the testing scenario, it is not sufficient to just adapt the settings on the prosody server but also on the ap-router in addition to opening the ports with an ACCEPT rule, traffic must be redirected from the ap-router to the prosody router’s IP. Therefore the /etc/config/firewall file on the ap router should be amended as follows:

[alert type=”danger” icon-size=”normal”]Be sure to remove these settings once you have finished testing. It is always advisable to not open or forward unnecessary ports on your firewall![/alert]

Prepare MySQL database

For first use, you have to set up the database and the user you have specified in your config file:

Fire up the server

Once these setup tasks are completed, you can fire up the server with

Prosody is quite a tight-lipped guy. In case it just says nothing you can assume that your server was launched correctly.

Once the server is running, you can add users as follows:

As long as /etc/prosody/prosody.cfg.lua holds the setting allow_registration = true you can even register from clients which have a “create account functionality such as Pidgin:

Extended functionalities

The XMPP server is able to handle any communication including text, audio and video chats, both encrypted and clear. There are some problems with incompatible file transfer protocols though – but these are not related to the server but rather to clients implementing file transfers differently (i.e. if both parties use the same client, it is no problem to make a file transfer).

Troubleshooting: /etc/hosts on client machine

In case a client machine has a “short cut” entry for hobbykeller.spdns.de, this will prevent clients from connecting to the server correctly. You have to comment out this entry in /etc/hosts.