prosodyctl shell

Prosody comes bundled with a powerful built-in shell, which can be used to interact with Prosody while it is running, and apply changes without restarting the server.

This interface used to be accessed via telnet, however the shell is now accessed via prosodyctl shell instead, which is more secure.

mod_admin_shell needs to be loaded in your configuration file (it is already present in the default configuration, but if you are upgrading from an older release you may need to add it (and remove mod_admin_telnet).

The shell provides a large range of commands out of the box which make it easy to load, unload and reload modules, show client to server and server to server connections, manage user accounts, and much more. Modules may also provide additional commands.

You connect to the shell by executing:

sudo prosodyctl shell

About commands

All Prosody’s shell commands are arranged into sections, such a “module” (module management), “user” (user account management), etc. For example, to load a module In the interactive shell, you would type:

module:load("some_module")

Shortcut

Sometimes you may not need to launch into the interactive shell just to execute a single command. In such cases you can specify the section and the command name directly to prosodyctl, followed by any parameters. For example, the command above can also be invoked directly like this:

prosodyctl shell module load some_module

For consistency, this documention uses the first style, but all commands can also be executed via the shortcut method.

Built-in commands

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.

user:disable(jid)

Disable a user account to prevent the user from logging in.

user:enable(jid)

Enables a user account that was previously disabled.

Real-time monitoring

watch:log()

Streams debug logs in real-time (does not require debug logging to be enabled in the config). This can be useful to capture debug logs without writing them to a file.

watch:stanzas(target, filter)

Shows stanzas sent/received by the target, which match the (optional) filter.

Both the target and filter are interpreted as JIDs, which may be domains.

For example, to view all stanzas on localhost (without filtering):

watch:stanzas("localhost")

The difference between target and filter is that target is used to match sessions (either c2s or s2s) and (if specified) filter is used to limit results to stanzas exchanged with a particular JID.

Limitations:

This command is intended for development/diagnostic purposes
It may not perform well on large/busy servers
Pre-authentication stanzas are not shown (i.e. it is not possible to capture the authentication step, or anything before it)
The displayed stanzas have been parsed and reformatted by Prosody, and may not identically match the stanza that was received on the wire

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.