prosodyctl

Prosody comes with a small utility to control the server, and manage users, etc. This is prosodyctl. It (currently) doesn't support Windows.

As an aid to those migrating from ejabberd, who may have existing scripts, prosodyctl is compatible with ejabberdctl wherever possible, this includes the register and unregister commands, despite these being hidden from the prosodyctl command listing by default.

Usage

The basic usage of prosodyctl is:

 prosodyctl COMMAND [OPTIONS]

Where COMMAND may be one of:

User management

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

Process management

Do not use these to start and stop Prosody unless you know what you are doing. Instead, use your distributions init system tools, e.g. systemctl.

start - Start Prosody

stop - Stop a running Prosody server

restart - Restart Prosody

reload - Reload Prosody's configuration and re-open log files

status - Reports the running status of Prosody

Other

shell - Securely connects to the Prosody console

cert … - Certificate management commands

Plugin management

install mod_plugin - Install a plugin using the Plugin installer

remove mod_plugin - Remove a plugin using the Plugin installer

list - List plugins installed using the Plugin installer

Informative

about - Shows information about the installation, including versions and paths

check WHAT - Perform various configuration and setup self-checks

Flags

An alternative configuration file can be given by --config /path/to/config.cfg.lua.

When invoked as root, prosodyctl will try to switch to the prosody user before proceeding. This can be disabled with --root.

Using prosodyctl

Because prosodyctl needs to switch to the same user that Prosody runs as, you need to run it as root, or otherwise ensure that you are logged in as the same user as Prosody runs as first. On Ubuntu and other systems you can do this by simply prepending 'sudo' to the command, like this:

 sudo prosodyctl status

If you installed your Prosody manually, then you will need to tell prosodyctl which user Prosody runs as. This is simple, just add the following line to the global section of your config file:

   prosody_user = "username"

You may also replace "username" with a numeric UID (in this case you wouldn't use quotes) if you need to.

If you installed Prosody from a package (e.g. using apt or another package manager) then you should already have an init script for controlling Prosody, and it is recommended to use that instead of prosodyctl for starting and stopping the server. On most systems this would be:

sudo systemctl start prosody

or

 sudo /etc/init.d/prosody start

Where 'start' can also be 'stop', 'restart' and 'reload'. Reload will cause the configuration file to be reloaded (no guarantees that changes will appear instantly though, in 0.4) and also re-open the log files (useful as part of log rotation).

pidfile

If you are not using one of our ready-made packages then to use prosodyctl you will need to tell it where to store its pidfile. Prosodyctl looks for this file to find whether Prosody is running. If you have multiple Prosody daemons running on the same machine, they must all use different pidfile locations. The pidfile and daemonization support is provided by the mod_posix module, so ensure that is loaded in your config.

Setting a pidfile location is as simple as:

   pidfile = "/var/run/prosody/prosody.pid" -- this is the default on Debian

or

   -- This one works great if you run Prosody direct from where you checked it out
   -- (ie. you use "./prosodyctl start")
   pidfile = "prosody.pid" -- stores prosody.pid in the current directory

⚠️ Note that the pidfile option has to be in the global section of the config.

Just make sure Prosody has the necessary permissions to create, modify and delete the file you tell it to use.