This site is now 100% read-only, and retired.

Using the prosody xmpp/chat server

Posted by Steve on Mon 10 Feb 2014 at 09:07

Prosody is a Lua-powered chat-server, which has been around for a few years now. Prosody is very straight-forward to install and configure, and the reliability means that it is a perfect way to provide chat-services to a small office, company, or group of friends. This brief article will cover installing it, both natively and within docker, along with a few pointers to things you can do with it.

Prosody is a XMPP-based chat-server, which allows multiple users to chat to each other, either directly (person-to-person) or via "conference rooms".

Conference-rooms are similar to IRC-channels, they allow multiple people to join the same space and chat freely to all participants.

Because XMPP is an open standard there are many clients you can choose from, available for a large number of operating systems. Popular clients include Pidgin, PSI, and empathy.

If you're new to XMPP-based chat there's nothing too much to learn, except that all logins for chat-servers consist of both a username and a domain-name - so you'll login to a chat server with what looks very much like an email address.

Installing Prosody

As always prosody can be installed easily using apt-get or aptitude:

root@chat ~ # apt-get install prosody

Once installed the configuration of the server consists of two parts:

  • The main configuration file, /etc/prosody/prosody.cfg.lua.
  • The configuration directory /etc/prosody/conf.d/

The main configuration file controls the servers global options, then includes files from beneath the conf.d/ directory - which is where you'll create configuration for each of your virtual hosts.

As mentioned earlier XMPP servers deal with user-accounts which have two parts: A username, and a domain-name.

To get started we just need to create a configuration file for our domain. Create the file /etc/prosody/conf.d/ with contents:

-- Virtual host for our chat-server

-- Define the host.
VirtualHost ""

-- Allow MUC / conference-rooms
Component "" "muc"
  name                   = "Chatrooms"
  restrict_room_creation = false

Once you've done that you can restart the service:

root@chat ~ # /etc/init.d/prosody restart

Your server should now be ready, and will allow two things:

  • Connection from users with logins "".
  • The creation of arbitrary "rooms".

If you were creating a chat-server for your own company, or domain, at this point you'd configure the DNS record to point to the IP address of your server.

It isn't strictly necessary to setup DNS, as most chat-clients allow you to specify both a username (of the form "") along with the actual server-name to connect to (which you would set to the IP of your server).

Firewalling Note

If you're only concerned with users chatting to each other, via the server, you only need to open port 5222 on your firewall.

Creating Accounts

There are two main ways you can configure account setup on the chat-server:

  • Permissively:
    • You allow anybody who can access the server to register their own account.
  • Strictly:
    • You explicitly create accounts for all the users you desire.

These two options are configured via the main server configuration file /etc/prosody/prosody.cfg.lua via the setting:

-- Disable account creation by default, for security
-- For more information see
allow_registration = false;

With this setting, as noted, the default, you must create your user accounts manually - which you can do by running:

root@chat ~ # prosodyctl register LOGIN DOMAIN PASSWORD

For example you might create the account with password "reallys3cr3t" like so:

root@chat ~ # prosodyctl register steve reallys3cr3t

If you prefer to allow users to register themselves then you set the value of allow_registration to be true, and restart the server. If your server is not firewalled away from the world expect you'll find spam accountss have registered themselves eventually.

NOTE: Most clients allow new accounts to be registered easily, for example on the account setup page of Pidgin there is a checkbox "Create account on server".

Installing via Docker

Recently I posted a pair of introductions to Docker (One + Two), and if you found that as interesting as I did you'd naturally be tempted to install prosody within such a container.

Happily the process isn't difficult, and I created this Dockerfile within a small Dockerfile repository.

If you have docker installed you can either rebuild this image by running the following from the directory containing the Dockerfile:

root@host# docker build -t skxskx/prosody .

Alternatively you may download the binary image I've previously created directly from the docker index:

root@host# docker pull skxskx/prosody

Either way you may now launch the server by running:

root@host#  docker run -d -p 5222:5222 skxskx/prosody

Once you've done that you'll have an ephemeral prosody instance running upon localhost:5222, and you can register an account, and create arbitrary rooms immediately.


You'll need to use your chat-client to register the account "", but tell it to connect to localhost:5222.

Once you've created a login, or two, you can create rooms beneath the prefix - for that you shouldn't need to specify "localhost", since that will be implicit.

Useful Scripts

I've found that even if you have a chatserver running with just an account for yourself you can still do interesting things.

This is largely because of the number of bots/alerter systems which understand how to speak XMPP. (You'll almost certainly need to create an account for them on the server, whether via the prosodyctl helper, or via your client.)

For example every morning I receive notices in the room "notices", from the servers that I manage. Similarly there are a small number of websites that I follow obsessively, and I regularly poll their RSS feeds, posting a message to a "feeds" room when they update.

Most of my messages are injected via a simple node.js application which listens for HTTP POST requests, and forwards their contents onto the chat-server:

There are alternatives which are easier to install though, such as the venerable sendxmpp package.

Those are just alerting systems though, there are also bots you can configure which will respond to messages in rooms of which they are members to run internet-searches, perform dictionary lookups, and similar things.

Future Expansion

Once you've got the server running you might want to explore federation, which allows you to configure your server to talk to other servers - seamlessly letting you chat with users on different networks.

Personally I've never needed that, or configured it, but providing your other servers are fully open there shouldn't be a problem.



Re: Using the prosody xmpp/chat server
Posted by Anonymous (31.24.xx.xx) on Mon 17 Mar 2014 at 01:06
Your article made me migrate from ejabberd to prosody and so far I'm happy, prosody seems more admin-friendly. Thanks!

[ Parent ]