prosodyctl

Show the status of the Prosody server

$ sudo prosodyctl status

$ sudo prosodyctl reload

$ sudo prosodyctl adduser [user@example.com]

$ sudo prosodyctl passwd [user@example.com]

$ sudo prosodyctl deluser [user@example.com]

prosodyctl [OPTIONS] COMMAND [ARGS]

-h, --help
    Displays a brief help message and exits.

-c path, --config=path
    Specifies the path to the Prosody configuration file. Defaults to /etc/prosody/prosody.cfg.lua or similar.

-D path, --datadir=path
    Specifies the path to the Prosody data directory, where user data and other persistent information is stored.

-p path, --pidfile=path
    Specifies the path to the PID file used by the Prosody daemon.

-H hostname, --host=hostname
    Specifies the virtual host for commands that operate on a specific domain (e.g., user management commands).

-u username, --user=username
    Specifies the username for commands that operate on a specific user account.

-P password, --password=password
    Specifies the password for user management commands. Use with caution as it exposes the password in command history.

-X, --no-modules
    Prevents Prosody from loading any modules when starting (primarily used for debugging).

-V, --version
    Displays the Prosody version information and exits.

-v, --verbose
    Increases the verbosity of the output, showing more details about operations.

-q, --quiet
    Decreases the verbosity of the output, suppressing non-essential messages.

--daemon
    Used with the 'start' command to run Prosody in daemon mode (background).

prosodyctl is the primary command-line utility used to control and manage the Prosody XMPP server. It provides a unified interface for administrators to perform a wide range of tasks, including starting, stopping, and restarting the server, managing user accounts (e.g., adding, deleting, changing passwords), inspecting server status and logs, generating and managing SSL/TLS certificates, and dynamically enabling or disabling modules. The command simplifies common administrative operations by interacting with the running Prosody daemon via a control socket, allowing many changes to take effect without requiring a server restart. It's an essential tool for day-to-day administration of a Prosody XMPP instance.

Many prosodyctl commands require appropriate permissions, often root or the user under which Prosody runs, to interact with the daemon or modify system files (e.g., starting/stopping the server, generating certificates).
For most commands to function, the Prosody server daemon must be running and its control socket accessible. If the server is stopped or the socket permissions are incorrect, commands interacting with the daemon will fail.

prosodyctl supports a variety of commands for different administrative tasks:
start, stop, restart, status, debug, reload (for config changes), adduser, deluser, passwd, register, unregister, cert (generate/request/verify certificates), modules (enable/disable/list), diagnose, shell (for interactive Lua console), and help.

The primary mechanism for prosodyctl to communicate with a running Prosody instance is via a Unix domain socket, typically located at /var/run/prosody/prosody.sock or a similar path. This enables secure and efficient inter-process communication for administrative tasks without relying on network ports.

prosodyctl was developed as an integral part of the Prosody XMPP server project, which was initiated in 2008 by Matthew Wild. Its design philosophy aligns with Prosody's core tenets of being lightweight, modular, and easy to configure. The utility has evolved alongside the server, incorporating new commands and options to reflect Prosody's expanding feature set and administrative needs. It leverages Prosody's robust internal control socket mechanism, which was a key design choice to enable dynamic server management without frequent restarts.

prosody(8), systemctl(1), service(8)