Console

Prosody comes bundled with a mod_admin_telnet plugin. Enabling this plugin starts a telnet console to let you communicate with a running Prosody instance. The console is very powerful, and enables you change things without restarting the server.

Supplied commands make it easy to load, unload and reload modules, show client to server and server to server connections and much more.

Using the advanced mode allows for easy debugging of Prosody at runtime also.

To use any of these commands you need to have the module “admin_shell” in your config file. You connect to the console by executing:

sudo prosodyctl shell

Prior to Prosody 0.12.x, these commands were only available by enabling the module "admin_telnet" in your config file and connecting to the console by executing:

telnet localhost 5582

Modules

module:load(module, host)

To load a module on all hosts, simply run:

module:load("module")

If you only want to load it on a single host, perhaps example.org:

module:load("module", "example.org")

module:reload(module, host)

Quite often after editing and reloading the server configuration, you will want to reload a module to have the changes take effect.

Let's reload the pep module on all hosts:

module:reload("pep")

Too personal? Let's unload pep just from example.com:

module:unload("pep", "example.com")

Check if a module is loaded

> require"core.modulemanager".is_loaded("host", "module")

Client (c2s) commands

c2s:show(host)

Show current client connections on all hosts:

Show current client connections only on a specific host:

c2s:show("example.org")

c2s:close(jid)

Close a user's session. The supplied JID may either be 'bare' (ie. user@example.com) to close all connections for that account or 'full' (ie. user@example.com/Office) to close only that session.

Example:

c2s:close("romeo@shakespeare.lit")

c2s:show_secure()

Show all secure (encrypted) connections. Removed in 0.12.0, see the ‘secure’ column in c2s:show()

c2s:show_insecure()

Show all insecure (unencrypted) connections. Removed in 0.12.0

Server-to-server (s2s) commands

s2s:show()

Show current s2s connections on all hosts.

s2s:show("example.org")

Show current s2s connections on a specific host.

s2s:close(from, to)

Close an s2s connection.

For example to close a connection from example.org to jabber.org:

s2s:close("example.org", "jabber.org")

Server commands

server:shutdown(reason)

Begin shutting down the server. An optional reason can be sent to all connections when they are closed to tell them why the server is stopping.

server:uptime()

Report for how long the server has been running.

server:version()

Report the version of the running server.

Configuration commands

config:reload()

Reload the server's configuration file. Note that not all changes may take effect, for example you may need to reload affected modules.

Host commands

host:list()

List all the hosts currently configured (but not necessarily enabled) for the server.

host:activate(host)

Activates a given host. If changes have been applied to the config you may need to reload it.

host:deactivate(host)

Deactivates a given host.

MUC commands

muc:room(room)

Fetches the room object. Not very useful by itself, but has some useful methods.

muc:room(room):get_affiliation(jid)

Shows what affiliation jid has in the room.

muc:room(room):set_affiliation(actor, jid, affiliation)

Sets affiliation for jid in the room. Pass true as first argument. Possible values for affiliation are "owner", "admin", "member", "outcast" (banned) and "none" (no affiliation).

muc:room("room@muc.host"):set_affiliation(true, "user@host", "member");

muc:room(room):get_role(nick)

Shows what role the user with nickname nick has in the room.

muc:room(room):destroy()

Kicks everyone from the room and removes it.

Destroying a room leaves a tombstone, preventing the room from being mistakenly re-created. Calling :destroy another time destroys the tombstone and allows the room to be created again.

muc:room(room):save(force)

Commits the room to storage. Passing true as argument ensures that non-persistent rooms are removed.

User management

user:create(jid, password)

Create the specified user account.

user:password(jid, password)

Set the password for the specified user account.

user:delete(jid)

Permanently remove the specified user account.

user:list(hostname, pattern)

List users on the specified host, optionally filtering with a pattern.

Leaving the console

Type either bye or quit to end the console session.

Advanced usage

The console can also be used to access server internals at runtime, this can be done by prefixing a line with the > character. For example:

> hosts
| Result: table: 0x80dffe0

This is most useful to those debugging or otherwise familiar with Prosody's internals.