Prosody Server Setup 0.10 (XMPP)

Prosody Server Setup 0.10 (XMPP)


Prosody is a free open-source XMPP server written in Lua. It’s fast and lightweight. XMPP is a great protocol for instant messaging. We’ll go through Prosody server setup on Ubuntu 16.04/17.04.

Prosody logo


Prosody is already present by default, so simply type:

$ sudo apt install prosody

There is a chance default version is 0.9 (or less), to install newest version,  add APT respository. Create: /etc/apt/sources.list.d/prosody.list, and add:

deb xenial main

To download and import Prosody public key (allowing APT manager to verify the integrity of packages on this repository), run:

$ wget -O- | sudo apt-key add -

Update and install:

$ sudo apt update
$ sudo apt install prosody

To enable/run at boot time:

$ sudo systemctl enable prosody

Configure Prosody


Main configuration file is placed on /etc/prosody/prosody.cfg.lua . In module_enabled section, uncomment (remove –) or comment (add –) lines to disable or enable specific modules. At the moment, there are ~300 prosody modules available.

Virtual Host

In older versions:

VirtualHost ""
      enabled = true  
      ssl = {
          key = "/etc/prosody/certs/your-privkey.pem";
          certificate = "/etc/prosody/certs/your-cert.pem"; }

In newer 0.10.x version, things are a bit confusing. It seems you need to define certs/keys before VirtualHost (although cert is already present there):

https_certificate = "/etc/prosody/certs/";
https_key =  "/etc/prosody/certs/";

VirtualHost ""
            certificate = "/path/to/example.crt

Also, enable encryption:

c2s_require_encryption = true;
s2s_secure_auth = true;

Note: Do not place anything after VirtualHost segment, place everything in Server-wide segment. I’ve experienced issues like:

No certificate/key found for https
Error binding encrypted port for https: No certificate present in SSL/TLS configuration for https port 5281

In case you encounter some problems, don’t forget to set debug mode in prosody config for log configuration.

If BOSH is enabled, it should be available on or

Visiting one of those URLs should show you something like:

It works! Now point your BOSH client to this URL to connect to Prosody.
For more information see Prosody: Setting up BOSH.

A BOSH endpoint for clients to connect to XMPP via HTTP.

Enable Registration from XMPP Client

To allow user registration from XMPP client, enable register module and set:

allow_registration = true;

Check syntax:

luac -p /etc/prosody/prosody.cfg.lua

and restart:

sudo systemctl restart prosody

Prosody User Accounts

Prosody Management (prosodyctl)

Usage: /usr/bin/prosodyctl COMMAND [OPTIONS]

Where COMMAND may be one of:

                                              adduser JID : Create the specified user account in Prosody
                                               passwd JID : Set the password for the specified user account in Prosody
                                              deluser JID : Permanently remove the specified user account from Prosody
                                                    start : Start Prosody
                                                     stop : Stop a running Prosody server
                                                  restart : Restart a running Prosody server
                                                   reload : Reload Prosody's configuration and re-open log files
                                                    about : Show information about this Prosody installation
                                                    check : Perform basic checks on your Prosody installation
                  cert config|request|generate|key|import : Helpers for generating X.509 certificates and keys.
                         cert config HOSTNAME [HOSTNAME+] : Builds a certificate config file covering the supplied hostname(s)
                                 cert key HOSTNAME <bits> : Generates a RSA key named HOSTNAME.key , Prompts for a key size if none given
                        cert request HOSTNAME [HOSTNAME+] : Generates a certificate request for the supplied hostname(s)
                       cert generate HOSTNAME [HOSTNAME+] : Generates a self-signed certificate for the current hostname(s)
  cert import [HOSTNAME+] /path/to/certs [/other/paths/]+ : Copies certificates to /var/lib/prosody
                                                   status : Reports the running status of Prosody

To add user:

$ sudo prosodyctl adduser

To change password:

$ sudo prosodyctl passwd

In order to specify admins, you need to add the account(s) in configuration file:

admins = { "", "" }

To list users, you can add module , then run:

$ prosodyctl mod_listusers

To enable anonymous users, instruct a host to allow anonymous logins:

VirtualHost "" -- Replace with your domain
   -- Enable anonymous login:
   anonymous_login = true -- in Prosody 0.7
   authentication = "anonymous" -- in Prosody 0.8+

   -- Allow anonymous users to access remote servers:
   disallow_s2s = false -- Prosody 0.8
   allow_anonymous_s2s = true -- Prosody 0.9+, default: false, risky , check docu

If you are mixing authenticated and anonymous services then it is recommended to set up a subdomain for anonymous users, like "".

Multi-User Char Room

For MUC  (Multi-User Chat) add your domain name to prosody configuration:

Component "" "muc"

Restrict room creation, available options:

           false : The default. No restrictions, anyone can create rooms. 
 true or "admin" : Restricts room creation to service administrators only. 
         "local" : Restricts room creation to users on the service's parent domain. 
                   E.g. can create rooms on

e.g. restrict_room_creation = false

Proxying requests

Traditional solution to same-origin problem is to have the web server acts as a proxy to the real BOSH server at some URL. For e.g. configuring web server to forward requests for to

Note: If your web server does https and you proxy to Prosodys http port, it will think that connections are insecure and may not offer some features. To correct this, add consider_bosh_security = true to prosody configuration file.

To proxy an URL:


Make sure you have modules enabled:

sudo a2enmod rewrite proxy proxy_http

Apache config:

 <Location /http-bind>
     Order allow,deny
     Allow from all
 RewriteEngine On
 RewriteRule ^/http-bind$ [P,L]

If your XMPP server is on the same machine as web server, replace with localhost (it will be more efficient using loopback interface, without DNS lookups)


Set the following config:

 location /http-bind {
     proxy_pass http://localhost:5280/http-bind;
     proxy_set_header Host $host;
     proxy_set_header X-Forwarded-For $remote_addr;
     proxy_buffering off;
     tcp_nodelay on;



 server.modules += ( "mod_proxy" )
 proxy.server = (
     "/http-bind" => (
         ( "host" => "", "port" => 5280 )

XMPP Client(s)

These clients and libraries support BOSH and have been tested against Prosody:

  • Desktop: Gajim
  • Desktop: Pidgin
  • C++ library: gloox
  • Javascript: Strophe.js (and Strophe based applications, including Candy)
  • Javascript: JSJaC (and JSJaC applications, including Jappix, JWChat, MUCkl and iJab)
  • Javascript: node-xmpp-client for Node.js
  • Lua: Verse

There are many libraries and clients at your disposal, for wide variety of platforms our there.

Prosody Cert vs Let’s encrypt

There were some issue related to cert expiration/update and sync with Let’s encrypt (permissions). Instead of chaning ownership or doing things manually you can use prosody itself to do this:

$ prosodyctl --root cert import /etc/letsencrypt/live

You can also create hooks on let’s encrypt side to automate this process on each cert renewal. Check Let’s encrypt Setup (segment on Hooks)

Additional Info

In order to avoid restarting prosody every time you change your config/add modules (dropping online users), you have a mod_reload_modules, check it out. You can also check this Prosody XMPP performance test (a bit outdated, tested with Artillery).


One of many XMPP servers out there. Prosody is simple, lite and in general does a pretty good job (including a great usage of system resources). A “community project” with a huge number of modules, maybe not popular as ejabberd or Google XMPP server, but good enough for my taste.

Documentation Box
Download Box