13.0

• Lua 5.1 no longer supported
• LuaSQLite3 can be used to provide SQLite3 support instead of LuaDBI.
• All Lua modules moved under a single namespace, so e.g. prosody.util.stanza which should allow Prosody to be installed the same way as other Lua packages. A prosody.loader module is introduced to provide backwards compatibility. See #1223.

0.12

• New dependencies:
  • lua-readline for the console
  • luarocks for plugin installer
  • luaunbound for more reliable DNS support
  • LuaLDAP for mod_auth_ldap
• server_epoll is the new default network backend, which has a hard dependency on LuaSec, unlike older network backends.
• [ICU] is now the recommended string normalization library (details in issue #533), replacing libidn

0.11.5

• The prosody executable now supports command line flags to control daemonization, -D to daemonize and -F to force foreground operation, meant to be used in service/init scripts.

0.11

• Lua 5.2 is now the recommended version, but Lua 5.1 is still supported. Lua 5.3 is still not officially supported.
• make test now runs tests using Busted and lints with luacheck.
• The utility util.time has been rewritten in C to gain access to clock_gettime(). Systems with glibc before 2.17 may need to be linked with -lrt to work. See #1219
• Makefile renamed GNUmakefile to reflect use of GNU-isms. There’s also a makefile meant to be compatible with BSD make.

Prosody versioning

Prosody versions consist of three components, x.y.z, e.g. 13.0.1.

Our release branches are identified by the first two components (x.y), e.g. 0.12 or 13.0. Patch releases, which introduce only bug fixes will increase the last component (z).

To summarize, for our version numbers x.y.z:

• x.y: Increases between major releases, which may add or deprecate features. E.g. 0.11 to 0.12, 13.0 to 13.1, or 13.0 to 14.0.
• z: Increases for bug fixes and minor changes. E.g. 0.12.3 to 0.12.4, or 13.0.0 to 13.0.1.

Release branch lifecycle

Each Prosody release branch (as identified by the first two components of the version number) begins with a .0 release (such as 0.12.0 or 13.0.0).

From this first release onwards, we commit to including only bug fixes or non-disruptive small improvements in that series. For example, you can safely update from 0.12.0 to 0.12.1 without fear that you will need to deal with breakage.

Our general policy is to support a branch for as long as it is included in a non-end-of-life version of Debian. This excludes Debian LTS.

Current branches:

• 13.0: TBA
• 0.12: Included in Debian 12 (bookworm). Support ends in June 2026.
• 0.11: Included in Debian 11 (bullseye). Not supported since August 2024.

Lua versions

Recommended Lua versions by Prosody release:

• 13.0: Lua 5.4 (recommended), Lua 5.2/Lua 5.3 (supported)
• 0.12: Lua 5.4 (recommended), Lua 5.2/Lua 5.3 (supported)
• 0.11: Lua 5.2 (recommended), Lua 5.1 (supported), Lua 5.3 (experimental)

All Lua 5.1 (and, implicitly, LuaJIT) support has been removed from 13.0 and later.

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 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/prosody.pid"

mod_posix

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.

Logging

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 {
        daily
        rotate 14
        compress
        postrotate
                /etc/init.d/prosody reload > /dev/null
        endscript
        sharedscripts
        missingok
}

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
fi

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 desirable 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"