Table of Contents

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_telnet" in your config file. You connect 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

 > 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.

c2s:show_insecure()

Show all insecure (unencrypted) connections.

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

Note: This is new in 0.9

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 nil (no affiliation).

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. :!: Note: You need to call :save(true) afterwards in order to purge the room completely.

muc:room(room):save(force)

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

User management

Note: 0.9 and above.

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.