Information for packagers

Prosody's main goal is to be user-friendly and easy to use. One of the hardest parts of this task is getting the server installed and running in the first place. By providing reliable high quality packages then on most systems installing Prosody should take no more than a minute of the user's time.

If you're planning to, or already, maintain packages for Prosody, thanks! This page is here just for you. If you feel there is anything that should be added, or have any questions about how to best package Prosody feel free as always to ask us.



  • There's now a CHANGES file.
  • New optional dependency required for mod_websocket (only on Lua 5.1, other versions of Lua provide this out of the box): lua-bitop
  • In addition to Lua 5.1 and LuaJIT, Prosody now supports Lua 5.2. Although we still recommend Lua 5.1 for production usage, we encourage feedback and bug reports from Lua 5.2 users. Lua 5.3 may also work, but it currently not officially supported.
  • ./configure should now detect Lua version and the location of the files required to build.
    • If there are multiple versions, --lua-version=5.x should be specified. Especially if Lua 5.3 is available.
    • --runwith would usually only be used for eg setting LuaJIT as runtime, but this could also be done from an init script.
  • mod_posix is now automatically loaded on POSIX systems, therefore there is no need to patch it into the default config file like in previous versions.
  • Certificate handling has changed. We no longer recommend using the 'ssl' setting, and instead encourage users to rely on automatic location for a simpler workflow and better integration with Let's Encrypt
  • Removed modules (replaced with dummy modules that log an informational error):
    • mod_compression
    • mod_privacy (dummy module auto-loads mod_blocklist)
  • Added modules (for informational purposes, do not just add them to the config!):
    • mod_blocklist: Replacement for mod_privacy, faster and uses newer protocol (XEP-0191)
    • mod_carbons: XEP-0280 (sync conversations between connected clients)
    • mod_debug_sql: For, er, debugging SQL
    • mod_limits: Bandwidth rate limiting
    • mod_mam: Store messages in per-user archives (primarily used for conversation sync with offline devices)
    • mod_s2s_auth_certs: Auto-loaded internal module for authenticating remote servers based on certificate
    • mod_server_contact_info: Used to publish contact addresses of server admins (e.g. for handling abuse reports)
    • mod_storage_sql1: Deprecated storage module from 0.9, will be removed in future version
    • mod_unknown: Dummy module loaded when Prosody runs on an unknown platform
    • mod_websocket: New module that implements XMPP over Websocket connections
    • mod_windows: Module auto-loaded when running on Windows


  • The runtime can now be set with ./configure --runwith=lua5.1 if your distribution allows for installations of multiple Lua versions.
  • Certificates: As of 0.9.2 is it strongly recommended to pass --no-example-certs to ./configure if you are building packages for distribution. You should instead generate certificates at installation time on the end-users system if you wish to do so. Alternatively guide the user to create certificates themselves, as documented on our Certificates page.



The certs/ directory now contains a Makefile that can be used to generate OpenSSL configs for a given XMPP domain. In a future version this functionality shall be merged into prosodyctl.


  • New optional dependency, LuaDBI: luadbi (for SQL)
  • May use libICU instead of libIDN, use ./configure --idn-library=icu


  • New (simpler) logging config format recommended:
    log = {
             info = "/var/log/prosody/prosody.log"; -- Change info to debug for verbose logging
             error = "/var/log/prosody/prosody.err";
             "*syslog"; -- Additionally send all log messages to syslog (no effect without mod_posix)
  • util.ztact has been removed (some distros used it in their config file to include a directory)
  • Added support for wildcards to Include in the config, e.g. Include "conf.avail/*.cfg.lua"
  • Renamed mod_console to mod_admin_telnet
  • Added new plugins: mod_adhoc, mod_admin_adhoc


  • New optional dependency, luaevent-prosody: (repository) (tarball)
  • We have reformatted the config file, and added some options (diff).
  • New modules: mod_proxy65 (not for modules_enabled), mod_privacy
  • New folder 'sasl' in util/
  • Prosody now sets a umask of 027 to protect its data files
  • We now use our own mkdir() instead of LuaFileSystem's due to a bug in current versions



  • Optional dependency (0.8): luadbi (for SQL)
  • Hard dependency (undecided): nixio


Follows some common questions or issues that new packagers have or stumble upon.

Init script

Most platforms are using start-stop-daemon for their Prosody init scripts, as it is a little more flexible than prosodyctl at the moment. For reference, the Debian init script can be found here.

We also have user-contributed scripts for systemd as attachments to issue #280.

Pidfile option

In order for prosodyctl to locate a running Prosody, and (since 0.7) for Prosody to detect multiple running instances, you need to set the pidfile option in the default config. It needs to point to a filename that is within a directory writeable by Prosody. On Debian we use:

    pidfile = "/var/run/prosody/"


On POSIX platforms (that is well, all of them except Windows) you should make sure that mod_posix is enabled in the default config file. It adds features like syslog support, daemonizing, and writing the pidfile.


Check you have sensible defaults for Logging. If your platform uses logrotate or something similar then include a config file for that too.

As with the pidfile, the logs need to go into a directory writeable by Prosody.

Example logging config on Debian:

        -- Hint: If you create a new log file or rename them, don't forget to update the
        --       logrotate config at /etc/logrotate.d/prosody
        log = {
                -- Log all error messages to prosody.err
                { levels = { min = "error" }, to = "file", filename = "/var/log/prosody/prosody.err" };
                -- Log everything of level "info" and higher (that is, all except "debug" messages)
                -- to prosody.log
                { levels = { min =  "info" }, to = "file", filename = "/var/log/prosody/prosody.log" };

As noted, if usual on your platform then include a logrotate config for Prosody. Debian uses this:

/var/log/prosody/prosody.log /var/log/prosody/prosody.err {
        rotate 14
                /etc/init.d/prosody reload > /dev/null

Tip: Don't be tempted to use /var/log/prosody/prosody.* here :-). Finding sensible defaults is difficult, as log noise will vary depending on usage. We had rough consensus in the Prosody chatroom that 14 days of logs rotated daily was a decent mid-way point.

Prosody user account

Prosody never needs to run as root. Upon installation your package should create a system user, preferably called 'prosody', with a group of the same name. If you use another name then be sure to set prosody_user in the default configuration file.

A suitable user can be created with this shell code:

if ! getent passwd prosody >/dev/null; then
    adduser --disabled-password --quiet --system \
            --home /var/lib/prosody --no-create-home \
            --gecos "Prosody XMPP Server" --group prosody

Registration policy

For security reasons the default configuration file has in-band account registration disabled (allow_registration = false). Note that mod_register is still loaded though, because the same protocol is used for existing users to change their passwords. Admins are encouraged to use prosodyctl to create new users. See Creating accounts.

Data directory

On most systems the default data directory is /var/lib/prosody. This needs to be passed to ./configure using the –data-dir flag.

Make sure that upon installation the directory is created, owned by Prosody, and is not world-readable (the data files contain passwords and other sensitive information).

   chown prosody:prosody /var/lib/prosody
   chmod 750 /var/lib/prosody

Including separate files

Some systems might find it desireable to split the configuration file into multiple files. To achieve this you can use the Include directive. This also supports including files by wildcard.

Include "base_config.lua"
Include "vhosts.d/*.lua"


Some distributions have been using util.ztact to include multiple files from a directory. To achieve this with version 0.8 and higher you will need to replace

local ztact = require "util.ztact"
local cfgdir = "/etc/prosody/conf.d/"
for f in ztact.dir(cfgdir) do Include(cfgdir..f); end


Include "/etc/prosody/conf.d/*.lua"
doc/packagers.txt · Last modified: 2017/10/02 16:47 by Matthew Wild