Prosody

Prosody

Developer(s)	The Prosody Team
Initial release	December 3, 2008 (2008-12-03)
Stable release	0.9.12 / January 10, 2017 (2017-01-10)
Repository	hg.prosody.im
Written in	Lua
Operating system	Cross-platform
Type	XMPP server
License	MIT License
Website	prosody.im

XMPP Portal

XMPP Servers:	Servers Category
XMPP Clients:	Clients Category
User Guides:	User Guide Category

Prosody is a modern XMPP communication server. It aims to be easy to set up and configure, and efficient with system resources. Additionally, for developers it aims to be easy to extend and give a flexible system on which to rapidly develop added functionality, or prototype new protocols.

Prosody is open-source software under the permissive MIT license.

Prosody Server Build

Installing Prosody is quite straightforward in most cases. They have packages for the major operating systems to make it even easier. If they have no package for operating system, you should be able to install using the source package.

DNS Configuration

The DNS configuration for prosody is the same as for other XMPP servers. There are two main ways of configuring DNS for a XMPP server. The first method is to create normal A records pointing to your XMPP server (note; CNAME records are not allowed with most clients). The second way is to create SRV records that will give the port and server name of your XMPP server when queried.

The default port for clients to connect to is TCP port 5222, and the default port for other servers to connect to is TCP port 5269.

DNS Configuration with SRV Records

The standard way of configuring DNS for XMPP servers is via a SRV records pointing to an A record. This method allows for flexibility with the number of servers, the name of the servers, and the ports used.

For this example, we are going to assume that the IP address of the server that will be running Prosody is 12.34.56.78 and will be named server.example.com, and the domain name for the XMPP service is example.com.

server.example.com.              21600   IN   A     12.34.56.78
_xmpp-client._tcp.example.com.   21600   IN   SRV   0 5 5222 server.example.com.
_xmpp-server._tcp.example.com.   21600   IN   SRV   0 5 5269 server.example.com.

DNS Configuration with only A Records

The alternative way of configuring DNS for XMPP is via an A record, pointing directing at the XMPP server. The problem with this method is that the server must be named the same as the XMPP domain name.

So for this example, we are going to assume that the IP address of the server that will be running Prosody is 12.34.56.78 and will be named xmpp.example.com, and the domain name for the XMPP service is also xmpp.example.com.

xmpp.example.com.                21600   IN   A     12.34.56.78

DNS Conference Configuration

Similar to the client and server configuration above, conferences require a special DNS entry to allow other XMPP servers to connect to your conference service. You will need to setup a SRV or A record for that hostname also.

_xmpp-server._tcp.conference.example.com. 21600 IN SRV 0 5 5269 server.example.com.

Firewall Configuration

XMPP uses it's own ports to communicate with the client (TCP port 5222), and with other xmpp servers (TCP port 5269) threw a service called federation. In-order to properly use prosody, you must open TCP ports 5222 & 5269. You may use the iptables config provided.

Installing Prosody

Packet Manager

This Page was written with Ubuntu 16.04 LTS in mind, and may not work correctly with other versions or distributions.

The prosody development team provides a deb repository to for apt installs.

To set-up the repository on Ubuntu, run the following commands as root:

echo deb http://packages.prosody.im/debian $(lsb_release -sc) main |tee -a /etc/apt/sources.list
wget https://prosody.im/files/prosody-debian-packages.key -O- |apt-key add -
apt update

Then to actually install prosody, as root run:

apt install -y prosody lua5.1 liblua5.1-0-dev lua-filesystem lua-bitop lua-expat libidn11-dev \
libssl-dev lua-event lua-sec lua-zlib

From Source

apt install -y mercurial lua5.1 liblua5.1-0-dev lua-filesystem lua-bitop lua-expat libidn11-dev \
libssl-dev lua-event lua-sec lua-zlib

mkdir -p /var/src && cd /var/src && hg clone https://hg.prosody.im/0.10/ prosody-0.10 && \
 cd prosody-0.10 && ./configure --prefix=/usr --ostype=debian --with-lua-include=/usr/include/lua5.1 && \
 make && make install

Updating Prosody from Source

cd /var/src/prosody-0.10 && hg revert --all && hg pull -u && \
 ./configure --prefix=/usr --ostype=debian --with-lua-include=/usr/include/lua5.1 && \
 make && make install && service prosody restart

Prosody Server Configuration

/etc/prosody/prosody.cfg.lua

---------- Server-wide settings ----------
admins = { "[email protected]" }

-- This is the list of modules Prosody will load on startup.
modules_enabled = {
   -- Generally required
      "roster"; -- Allow users to have a roster. Recommended ;)
      "saslauth"; -- Authentication for clients and servers. Recommended if you want to log in.
      "tls"; -- Add support for secure TLS on c2s/s2s connections
      "dialback"; -- s2s dialback support
      "disco"; -- Service discovery

  -- Not essential, but recommended
      "private"; -- Private XML storage (for room bookmarks, etc.)
      "vcard"; -- Allow users to set vCards

  -- These are commented by default as they have a performance impact
      "privacy"; -- Support privacy lists
      "compression"; -- Stream compression (Debian: requires lua-zlib module to work)
      "version"; -- Replies to server version requests
      "uptime"; -- Report how long server has been running
      "time"; -- Let others know the time here on this server
      "ping"; -- Replies to XMPP pings with pongs
      "pep"; -- Enables users to publish their mood, activity, playing music and more
      "register"; -- Allow users to register on this server using a client and change passwords

  -- Admin interfaces
      "admin_adhoc"; -- Allows administration via an XMPP client that supports ad-hoc commands
      --"admin_telnet"; -- Opens telnet console interface on localhost port 5582

  -- HTTP modules
      "bosh"; -- Enable BOSH clients, aka "Jabber over HTTP"
      --"http_files"; -- Serve static files from a directory over HTTP

  -- Other specific functionality
      "posix"; -- POSIX functionality, sends server to background, enables syslog, etc.
      "groups"; -- Shared roster support
      "announce"; -- Send announcement to all online users
      "welcome"; -- Welcome users who register accounts
      "watchregistrations"; -- Alert admins of registrations
      "motd"; -- Send a message to users when they log in
};

allow_registration = false;
daemonize = true;
pidfile = "/var/run/prosody/prosody.pid";
ssl = {
   key = "certs/example.com.key";
   certificate = "certs/example.com.crt";
}

c2s_require_encryption = true
s2s_secure_auth = false
s2s_insecure_domains = { "dsi" }
s2s_secure_domains = { "openpgp.us" }
authentication = "internal_plain"
sql = { driver = "SQLite3", database = "prosody.sqlite" } -- Default. 'database' is the filename.

-------- Logging ---------
log = {
   -- Log files (change 'info' to 'debug' for debug logs):
   info = "/var/log/prosody/prosody.log";
   error = "/var/log/prosody/prosody.err";
   -- Syslog:
   { levels = { "error" }; to = "syslog";  };
}

----------- Virtual hosts ----------- 
VirtualHost "example.com"
   ssl = {
       key = "certs/example.com.key";
       certificate = "certs/example.com.crt";
   }

VirtualHost "example2.com"
   ssl = {
       key = "certs/example2.com.key";
       certificate = "certs/example2.com.crt";
   }

VirtualHost "example3.com"

Component "conference.example.com" "muc"
Component "conference.example2.com" "muc"
Component "conference.example3.com" "muc"

Creating new user accounts

There are two ways of creating new user accounts within prosody; in-band and command line.

In-band User Registration

In-band registration is a way for xmpp clients (remote users) to ask the server to create an account. Obviously enabling such a protocol on the open internet can lead your server open to abuse, so in the default configuration registration is disabled.

To allow registration for a host, make sure mod_register is loaded (that you have "register" in modules_enabled) and add this line:

 allow_registration = true

It is possible to secure account registration a bit by restricting it to particular IP addresses, or limiting how often an IP address can register an account. These options are described on our configuration page.

Via Command Line (prosodyctl)

On all platforms except for Windows (currently) Prosody has a command-line utility called prosodyctl. This can be used to add a user account like so:

prosodyctl adduser [email protected]

Prosody will then prompt you for a password, and you will be able to log into your account using your client.

For batch registration of accounts consider the prosodyctl register command, which allows you to specify everything on one line:

prosodyctl register me example.com mypassword

Logging

Prosody's logging configuration is very flexible. For those who want something simple however, this is also easy.

All log messages in Prosody have a 'level', which is basically a priority/urgency indicator. Most messages Prosody generates are at the 'debug' level, and can be safely ignored, unless you are trying to diagnose and/or report an issue. The next level is 'info', which is given to normal everyday messages about things happening on the server - client/server connections, for example. Two higher levels, 'warn' and 'error' show potential problems. A message of 'warn' usually does not require any action to be taken, and may indicate a bug in a client or server that Prosody is connected to. A message of type 'error' is potentially quite serious, and all such messages should be investigated by an administrator.

Logging to a single file

Now, many people simply want Prosody to log to a file. This is easy… in your config put:

log = "prosody.log" -- Can be any filename

Prosody will automatically log all messages with a level of 'info' and higher, that is… all messages except the noisy 'debug' level.

Split logging

If you want to send different log levels to different files or sinks, you can use a slightly more advanced config format:

log = {
    debug = "/var/log/prosody/prosody.log"; -- Send debug and higher here
    error = "*syslog"; -- Send error and higher to the syslog sink
}

The supported levels are: "debug", "info", "warn", "error".

Log rotation

Log rotation is the process of creating new log files and archiving the old ones on a regular basis to make sure that the log files do not get too large.

Prosody is compatible with tools like logrotate, which should work automatically if you installed Prosody using a pre-built package. If you installed Prosody from source or if your system package did not set up log rotation please see our documentation on logging for packagers, which includes an example logrotate configuration for Prosody.