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 shellPrior 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 5582Modules
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: 0x80dffe0This is most useful to those debugging or otherwise familiar with Prosody's internals.