ejabberdctl

NAME

ejabberdctl — a control interface of ejabberd Jabber/XMPP server

SYNOPSIS

ejabberdctl [−−node node] [vhost server] command [options]

DESCRIPTION

ejabberdctl is a front end to the ejabberd Jabber/XMPP server. It is designed to help the administrator control the functioning of the running ejabberd daemon.

OPTIONS

−−node node

Specifies remote Erlang node to connect to. Default value is ejabberd. If the node name does not contain symbol @ then actual node name becomes node@host where host is short hostname (usually it coincides with `hostname −s`). If the node name contain symbol @ and its hostname part is a FQDN then ejabberd will use so-called long names (see erl(1) manual page and look for options −name and −sname for details).

Examples of −−node option:

ejabberd Connect to locally run ejabberd server at node ejabberd@`hostname −s`.

ejabberd@otherhost Connect to remotely run ejabberd server at node ejabberd@otherhost.

ejabberd@localhost Connect to locally run ejabberd server at node ejabberd@localhost.

ejabberdctl honors ERLANG_NODE environment variable from /etc/default/ejabberd, see below.

vhost server

Specifies that command should be executed for virtual host server. There are only few commands that require vhost argument.

If there are no vhost server options then the command can be any of the following:

	debug		Attaches an interactive Erlang shell to a running ejabberd server. To detach it press Ctrl+G, q, <Return>.
	status		Requests status of the Erlang virtual machine where ejabberd server is running.
	stop		Stops the ejabberd server and Erlang virtual machine.

restart

Restarts the ejabberd server inside Erlang virtual machine. Note that if you want to change VM options (enable/disable kernel poll or SMP, increase number of ports or database tables) you have to stop ejabberd completely and then start it again.

reopen−log

Force the ejabberd server to reopen its log file (/var/log/ejabberd/ejabberd.log by default).

reopen−weblog

If module mod_http_fileserver is loaded then force the ejabberd server to reopen its weblog file.

register user server password

Register user user with password password at ejabberd virtual host server.

unregister user server

Unregister user user at ejabberd virtual host server.

backup filepath

Backup user database of the ejabberd server to file filepath.

restore filepath

Restore user database of the ejabberd server from backup file filepath.

install−fallback filepath

Install a backup to filepath as fallback. The fallback will be used to restore the database at the next start-up.

dump filepath

Dump user database of the ejabberd server to text file filepath.

load filepath

Restore user database of the ejabberd server from text file filepath.

import−file filepath

Import user data from jabberd 1.4 spool file filepath. For example, if filepath is .../example.org/user.xml then imported username will be user and it will be imported to virtual server example.org.

import−dir directorypath

Import user data from jabberd 1.4 spool directory directorypath. Directory name should be the name of virtual server to import users.

delete−expired−messages

Delete expired offline messages from ejabberd database.

delete−old−messages n

Delete offline messages older than n days from ejabberd database.

mnesiainfo

Show some information about the Mnesia system (see mnesia(3), function info).

mnesia

Show all information about the Mnesia system, such as transaction statistics, db_nodes, and configuration parameters (see mnesia(3), function system_info).

mnesia key

Show information about the Mnesia system according to key specified (see mnesia(3), function system_info for valid key values).

incoming−s2s−number

Print number of incoming server-to-server connections to the node.

outgoing−s2s−number

Print number of outgoing server-to-server connections from the node.

user−resources user server

List all connected resources of user user@server.

connected−users−number

Report number of established users’ sessions.

connected−users

List all established users’ sessions.

If there are vhost server options then the command can be the following:
registered−users

List all registered at the ejabberd server users (at virtual host server).

EXTRA OPTIONS

An optional module mod_ctlextra adds a number of other commands.

To enable the additional commands add it to {modules} section of ejabberd config file and make it looking as the following:

{modules,
[
...
{mod_ctlextra, []},
...
]}.

The new options are:
compile file

Compile Erlang source file file.

load−config file

Load config from file. Note that loading config to a database doesn’t mean reloading server. For example it’s impossible to add/remove virtual hosts without server restart.

remove−node nodename

Remove an ejabberd node nodename from the Mnesia database cluster.

delete−older−users days

Delete users that have not logged in the last days.

set−password user server password

Set password for user user@server to password.

export2odbc server outputdir

Export Mnesia tables on server to files in outputdir directory for subsequent import to a relational database system.

delete−older−messages days

Delete offline messages older than days.

srg−create group host name description display

Create shared roster group group at server host with displayed name name, description description and displayed groups display.

srg−delete group host

Delete shared roster group group from server host.

srg−user−add user server group host

Add user user@server to group group at server host.

srg−user−del user server group host

Delete user user@server from group group at server host.

srg−list−groups host

List the shared roster groups at server host.

srg−get−info group host

Get info on the group group at server host.

vcard−get user host data [data2]

Get data from the vCard of user@host. data (and optional data2) is a vCard node. For example data may be FN or NICKNAME. For retrieving email address use EMAIL USERID. Other options can be obtained from XEP-0054 (http://www.xmpp.org/extensions/xep−0054.html).

vcard−set user host data [data2] content

Set data to content for user@host vCard. data (and optional data2) has the same meaning as for vcard−get command.

add−rosteritem user1 server1 user2 server2 nick group subs

Add user2@server2 to user1@server1’s roster. Option subs must be one of the none, from, or both.

rem−rosteritem user1 server1 user2 server2

Remove user2@server2 from user1@server1’s roster.

rosteritem−purge [options]

Purge all roster items that match filtering options.

pushroster file user server

Push template roster in file file to user@server. The file contents must use the following format:

[{"bob", "example.org", "Bob’s group", "Bob’s nickname"},
{"mart", "example.org", "workers", "Mart"},
{"Rich", "example.org", "bosses", "Rich"}].

pushroster−all file

Push template roster in file to all users listed in the file file itself. The file contents must be in the same format as for pushroster command.

push−alltoall server group

Adds all the users at server server to each other’s roster using group group.

status−list status

Print the list of currently logged users with status status. Status can be either all or one of the following: available, chat, away, xa, dnd.

status−num status

Print the number of currently logged users with status status. Status can be either all or one of the following: available, chat, away, xa, dnd.

stats registeredusers

Print the number of currently registered users.

stats onlineusers

Print the number of currently logged users.

stats onlineusersnode

Print the number of currently logged users in the ejabberd node.

stats uptime−seconds

Print the uptime of ejabberd node in seconds.

get−cookie

Get the Erlang cookie of this node.

killsession user server resource

Kill user user@server/resource session.

If there are vhost server options then the command can be one of the following:
num−active−users days

Print number of users active in the last days days (at virtual host server).

status−list status

Print the list of currently logged to virtual host server users with status status. Status can be either all or one of the following: available, chat, away, xa, dnd.

status−num status

Print the number of currently logged to virtual host server users with status status. Status can be either all or one of the following: available, chat, away, xa, dnd.

stats registeredusers

Print number of registered users (at virtual host server).

stats onlineusers

Print number of logged users (at virtual host server).

ban−account username [reason]

Ban account: kick sessions and change password (at virtual host server).

ejabberdctl starts distributed Erlang node ejabberddebug (if run with

debug option) or ejabberdctl (if run with any other options). If the ejabberd server’s node name to connect to includes FDQN as a hostname Erlang option −name is used. Otherwise ejabberdctl uses short names (−sname option).

Note that ejabberdctl does not append hostname to its own node name leaving this to Erlang emulator. It usually follows `hostname −f` to find a hostname if long names are used or `hostname −s` in case of short names, but may fail in case of unusual networking settings. A known case of failure is using long names when `hostname −f` doesn’t return FDQN. If ejabberdctl cannot create Erlang node then it cannot control ejabberd server.

OPTIONS FILE

The file /etc/default/ejabberd contains specific options. One of them is used by ejabberdctl.

ERLANG_NODE Use specified string as Erlang node of ejabberd server to connect. It overrides default ejabberd node name. The string may take one of the following forms: nodename, nodename@hostname or nodename AT hostname DOT domainname.

FILES

/etc/default/ejabberd default variables

SEE ALSO

erl(1), ejabberd(8), mnesia(3).

The program documentation is available at http://www.process−one.net/en/projects/ejabberd/. A copy of the documentation can be found at /usr/share/doc/ejabberd/guide.html.

AUTHORS

This manual page was adapted by Sergei Golovan <sgolovan AT nes DOT ru> for the Debian system (but may be used by others) from the ejabberd documentation written by Alexey Shchepin <alexey AT sevcom DOT net>.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU General Public License, Version 2 any later version published by the Free Software Foundation.
On Debian systems, the complete text of the GNU General Public License can be found in /usr/share/common−licenses/GPL.