Provided by: ejabberd_2.1.11-1ubuntu2.1_amd64 
NAME
ejabberdctl — a control interface of ejabberd Jabber/XMPP server
SYNOPSIS
ejabberdctl [--node nodename] [--auth user host password] [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.
This command must be run either by a superuser or by the user ejabberd, otherwise it will fail to start
or to connect to the ejabberd instance.
OPTIONS
--node nodename
Specifies remote Erlang node to connect to. Default value is ejabberd. If the node name does not
contain a symbol @ then the actual node name becomes node@host where host is short hostname
(usually it coincides with `hostname -s`). If the node name contains a 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.
--auth user host password
If restriction of access to ejabberdctl commands is configured (see the "Restrict Execution with
AccessCommands" section in the Installation and Operation Guide), this option must be used to
authenticate the entity requesting execution of the command. user and host are the respective
parts of the entity JID and password is either a plain text password to authenticate that JID or
the MD5 hash of that password.
--concurrent
Due to the way ejabberdctl is implemented, it is normally not possible to run two instances of it
in parallel–the second one will fail. This is OK in a common case when ejabberdctl is only run
manually from time to time by a server administrator; if, conversely, there is a chance for
several instances of ejabberdctl to be active at the same time (say, automated registration of new
users on an actively used site), you can pass the --concurrent option to ejabberdctl which will
ensure no clash will ever occur.
Usage of the --concurrent option creates additional pressure on the server resources, and that is
why the behaviour it implements is not the default. This issue is described in more detail in
/usr/share/doc/ejabberd/README.Debian
Note that the semantics of this option can be changed in a future release.
COMMANDS
Some commands to ejabberdctl are single words, like status, and some are multi-word, like reopen-log; to
join the adjacent words of the multi-word commands you can use either the underline ("_") symbol or the
minus sign ("-") or a mixture of them, so all the following forms are valid: status_list_host, status-
list-host, status_list-host.
When run without any command specified, ejabberdctl prints the list of available commands and their short
descriptions.
The following commands can be used:
help [--tags [tag] | PATTERN]
The help command without any options does the same thing as running ejabberdctl without any
command specified — it prints the list of available commands along with their short descriptions.
The --tags option specified alone makes the help command print the list of supported "help tags"
which group ejabberdctl commands on the basis of their purpose (such as debugging commands, backup
commands etc).
The --tags option specified with a tag tag makes the help command print the list of commands
associated wih the help tag tag along with their short descriptions.
If the help command is followed by a word other than "--tags", this word is interpreted as a
pattern specifying a set of commands to print the help on. In this pattern, a "*" character
matches any number of characters, including zero, and a "?" character matches any single
character. Note that when running ejabberdctl with this form of the help command from the shell,
you have to protect the characters in the pattern from being interpreted by the shell.
debug Attache an interactive Erlang shell to a running ejabberd server. To detach it press Ctrl+G, then
input a character "q" and hit <Return>.
status Request status of the Erlang virtual machine where ejabberd server is running.
stop Stop the ejabberd server and its Erlang virtual machine.
stop-kindly delay announcement
Broadcast an announcement announcement to all connected users, wait delay seconds and then stop
the ejabberd server and its Erlang virtual machine.
This command is interactive: it dumps the progress of the shutdown sequence to stdout (including
waiting for the grace period to pass).
The announcement string is unconditionally interpreted as a sequence of UTF-8 characters no matter
what locale settings the server and ejabberdctl processes see.
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 files (/var/log/ejabberd/ejabberd.log and
/var/log/erlang.log by default). 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.
The directory in which filepath is located must be writable by the user "ejabberd".
restore filepath
Restore user database of the ejabberd server from backup file filepath.
The file filepath must be readable by the user "ejabberd".
install-fallback filepath
Install a backup to filepath as fallback. The fallback will be used to restore the database at the
next start-up.
The directory in which filepath is located must be writable by the user "ejabberd".
dump filepath
Dump user database of the ejabberd server to text file filepath.
The directory in which filepath is located must be writable by the user "ejabberd".
load filepath
Restore user database of the ejabberd server from text file filepath.
The file filepath must be readable by the user "ejabberd".
dump-table file table
Dump the specified database table to the specified text file.
The directory in which file is located must be writable by the user "ejabberd".
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.
The file filepath must be readable by the user "ejabberd".
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.
The directory directorypath and the files in it must be readable by the user "ejabberd".
mnesia-change-nodename oldnodename newnodename oldbackup newbackup
Reads the backup file oldbackup (which should have been created using the ejabberdctl backup
command) and writes its contents to the file newbackup while replacing in it all occurences of the
Erlang node name oldnodename with the newnodename.
This should be used to "migrate" the ejabberd database to the new hostname of the machine on which
ejabberd runs in case this hostname is about to change. This is because ejabberd is actually
served by an Erlang node which is bound to the name of the physical host to provide for
clustering.
rename-default-nodeplugin
Since release 2.0.0 and up to release 2.1.0, the implementation of publish-subscribe (pubsub) in
ejabberd used a plugin named "node_default" as the default node plugin. Starting from release
2.1.0 this functionality is provided by the new plugin named "hometree". In the case of upgrading
from an older version of ejabberd, its pubsub database might retain references to the old name of
this plugin, "node_default", and this command can be used to upgrade the pubsub database, changing
all these references to the new name - "hometree".
Note that ejabberd automatically runs this command if you update from an ejabberd release 2.0.5 or
older.
Running this command on already updated database does nothing.
delete-expired-messages
Delete expired offline messages from ejabberd database.
delete-old-messages n
Delete offline messages older than n days from ejabberd database.
mnesia info
Show some information about the Mnesia system (see mnesia(3), function info).
mnesia Show all information about the Mnesia system, such as transaction statistics, database 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
Print full JIDs of all established sessions, one on a line.
connected-users-info
Print detailed information of all established sessions, one session on a line, with each session
described as a list of whitespace-separated values: full JID, connection string (such as "c2s",
"c2s_tls" etc), client IP address, client port number, resource priority, name of an Erlang node
serving the session, session duration (in seconds).
connected-users-vhost server
Print full JIDs of all users registered at the virtual host server which are currently connected
to the ejabberd server, one on a line.
registered-users server
List all the users registered on the ejabberd server at the virtual host server.
get-loglevel
Print the log level (an integer number) ejabberd is operating on.
EXPORTING DATA TO PIEFXIS (XEP-0227) FORMAT
The commands described in this section require availability of the exmpp library which is not shipped
with ejabberd. Your can download its source code from http://exmpp.org.
export-piefxis dir
Export data of all users registered on all virtual hosts of the server to a set of PIEFXIS files
which will be stored in the directory dir.
The directory dir must be writable by the user "ejabberd".
export-piefxis-host dir host
Export data of all the users registered on the specified virtual host host to a set of PIEFXIS
files which will be stored in the directory dir.
The directory dir and the files in it must be readable by the user "ejabberd".
import-piefxis file
Import users' data from a PIEFXIS file file.
The file file must be readable by the user "ejabberd".
EXTRA OPTIONS
An optional module mod_admin_extra adds a number of other commands.
While it is enabled by default, you might want to check it is actually enabled in the configuration file
(especially if you're upgrading from pre-2.1 series of ejabberd).
To enable these additional commands add mod_admin_extra to the {modules} section of ejabberd config file
and make it looking as the following:
{modules,
[
...
{mod_admin_extra, []},
...
]}.
Most of additional commands possess extended descriptions which can be printed using ejabberdctl help
command
The new commands are:
add-rosteritem localuser localserver user server nick group subscription
Add to the roster of the user localuser registered on the virtual host localserver a new entry for
the user user on the server server, assign the nickname nick to it, place this entry to the group
group and set its subscription type to subscription which is one of "none", "from", "to" or
"both".
delete-rosteritem localuser localserver user server
Delete from the roster of the user localuser on the server localserver an entry for the JID
user@server.
ban-account user host reason
Ban the user user registered on the virtual host host. This is done by kicking their active
sessions with the reason reason and replacing their password with a randomly generated one.
kick-session user host resource reason
Kick the session opened by the user user registered on the virtual host host and having the
resource resource bound to it providing the reason reason.
change-password user host newpass
Change password of the user user registered on the virtual host host to newpass.
check-account user host
Exit with code 0 if the user user is registered on the virtual host host, exit with code 1
otherwise.
check-password user host password
Exit with code 0 the user user registered on the virtual host host has password password, exit
with code 1 otherwise.
check-password-hash user host passwordhash hashmethod
Exit with code 0 if the user user registered on the virtual host host has a password, the hash of
which, calculated using the hashmethod is equal to the hash passwordhash; exit with code 1
otherwise.
Allowed hashing methods are "md5" and "sha" (for SHA-1).
compile file
Compile and reload the Erlang source code file file.
The file file must be readable by the user "ejabberd".
load-config file
Load ejabberd configuration from the file file.
The file file must be readable by the user "ejabberd".
Note that loading config to a database does not mean reloading the server — for example it's
impossible to add/remove virtual hosts without server restart. In fact, only ACLs, access rules
and a few global options are applied upon reloading.
delete-old-users days
Delete accounts and all related data of users who did not log on the server for days days.
delete-old-users-vhost host days
Delete accounts and all related data of users registered on the virtual host host who did not log
on the server for days days.
export2odbc host path
Export Mnesia database tables keeping the data for the virtual host host to a set of text files
created under the specified directory path, which must exist and must be writable by the user
"ejabberd".
get-cookie
Print the cookie used by the Erlang node which runs ejabberd instance ejabberdctl controls.
get-roster user host
Print the roster of the user user registered on the virtual host host.
The information printed is a series of lines each representing one roster entry; each line consist
of four fields separated by tab characters representing, in this order: the JID of an entry, its
nickname, subscription type and group.
push-roster file user host
Push items from the file file to the roster of the user user registered on the virtual host host.
The format of file containing roster items is the same as used for output by the get-roster
command.
push-roster-all file
The format of file containing roster items is the same as used for output by the get-roster
command.
push-alltoall host group
All entries for all the users registered on the virtual host host to the rosters of all the users
registered on this virtual host. The created entries are assigned to the roster group group.
process-rosteritems action subs asks users contacts
FIXME no information available. Do not use.
get-vcard user host name
Print the contents of the field name of a vCard belonging to the user user registered on the
virtual host host. If this field is not set of the user did not create their vCard, and empty
string is printed (that is, containing only the line break).
For example name can be "FN" or "NICKNAME" For retrieving email address use "EMAIL USERID". Names
and descriptions of other supported fields can be obtained from the XEP-0054 document
(http://www.xmpp.org/extensions/xep-0054.html).
get-vcard2 user host name subname
Print the contents of the subfield subname of the field name of a vCard belonging to the user user
registered on the virtual host host. If this field is not set of the user did not create their
vCard, and empty string is printed (that is, containing only the line break).
set-vcard user host name content
Set the field name to the string content in the vCard of the user user registered on the virtual
host host.
set-vcard2 user host name subname content
Set the subfield subname of the field name to the string content in the vCard of the user user
registered on the virtual host host.
set-nickname user host nickname
Set the "nickname" field in the vCard of the user user registered on the virtual host host to
nickname.
num-active-users host days
Print number of users registered on the virtual host host who logged on the server at least once
during the last days days.
num-resources user host
Print the number of resources (that is, active sessions) the user user registered on the virtual
host host currently has. If the specified user has no active sessions, print the string "0".
resource-num user host num
Print the resource of a session number num the user user registered on the virtual host host has
currently open. num must be a positive integer, greater than or equal to 1.
If the session number specified is less than 1 or greater than the number of sessions opened by
the user, an error message is printed.
remove-node node
Remove the Erlang node node from the Mnesia database cluster.
send-message-chat from to body
Send a message of type "chat" from the JID from to the (local or remote) JID to containing the
body body. Both bare and full JIDs are supported.
send-message-headline from to subject body
Send a message of type "headline" from the JID from to the (local or remote) JID to containing the
body body and subject subject. Both bare and full JIDs are supported.
send-stanza-c2s user server resource stanza
Send XML string stanza to the stream to which the session user@server/resource is bound. The
stanza must be well-formed (according to RFC 3920) and the session must be active.
For example:
ejabberdctl send-stanza-c2s john_doe example.com Bahamas \
'<message id="1" type="chat"><body>How goes?</body></message>'
srg-create group host name description display
Create a new shared roster group group on the virtual host host with displayed name name,
description description and displayed groups display.
srg-delete group host
Delete the shared roster group group from the virtual host host.
srg-user-add user server group host
Add an entry for the JID user@server to the group group on the virtual host host.
srg-user-del user server group host
Delete an entry for the JID user@server from the group group on the virtual host host.
srg-list host
List the shared roster groups on the virtual host host.
srg-get-info group host
Print info on the shared roster group group on the virtual host host.
srg-get-members group host
Print members of the shared roster group group on the virtual host host.
private-get user server element namespace
Prints an XML stanza which would be sent by the server it it received an IQ-request of type "get"
with the
<element xmlns="namespace"/>
payload from user@server.
For example:
ejabberdctl private-get john_doe example.com \
storage storage:bookmarks
would return user's bookmarks, managed according to XEP-0048.
private-set user server element
Allows one to simulate user@server sending an IQ-request of type "set" containing element as its
payload; the payload is processed by the code managing users' private storage (XEP-0049 "Private
XML Storage").
The string element must be a well-formed XML obeying the rules defined for IQ-request payloads in
RFC 3920.
privacy-set user server element
Allows one to simulate user@server sending an IQ-request of type "set" containing element as its
payload; this payload is processed by the code managing privacy lists (XEP-0016 "Privacy lists").
The string element must be a well-formed XML obeying the rules defined for IQ-request payloads in
RFC 3920.
stats topic
Print statistics on the topic topic. The valid topics and their meaning are:
registeredusers Print the number of users registered on the server.
onlineusers Print the number of users currently logged into the server.
onlineusersnode Print the number of users logged into the server which are served by the current
ejabberd Erlang node.
uptimeseconds Print the uptime of the current ejabberd Erlang node, in seconds.
stats-host host topic
Print statistics on the topic topic for the virtual host host. The valid topics and their meaning
are:
registeredusers Print the number of users registered on the host host.
onlineusers Print the number of users currently logged into the server, which are registered on
the host host.
status-list status
Print the users currently logged into the server and having the presence status status. The
entries are printed one per line; each entry consists of the four fields separated by tab
characters, in this order: the node part of the user's JID, the host part of the user's JID, the
user's session resource, the priority of the user's session and the user's status description.
The status parameter can take the following values: "available", "away", "xa", "dnd" and "chat".
status-list-host host status
Print the users currently logged into the server which are registered on the virtual host host and
have the presence status status.
The available values for the status parameter and the format of the output data are the same as of
the status-list subcommand.
status-num status
Print the number of users currently logged into the server and having the presence status status.
The available values for the status parameter are the same as of the status-list subcommand.
status-num-host host status
Print the number of users currently logged into the server which are registered on the virtual
host host and have the presence status status.
The available values for the status parameter are the same as of the status-list subcommand.
user-sessions-info user server
Print detailed information on all sessions currently established by user@server. For each
session, one line of output is generated, containing the following fields separated by tab
characters: connection string (such as "c2s", "c2s_tls" etc), remote IP address, remote port
number, priority of the resource bound to this session, name of an Erlang node serving the
session, session uptime (in seconds), resource string.
NOTES
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.
ejabberdctl does not do anything by itself except for connecting to the running ejabberd instance and
telling it about the action requested by the user. Hence all the ejabberdctl's operations involving
writing or reading files or directories are actually performed by the server process which runs with the
uid and gid of the user and group "ejabberd", respectively. This must be taken into account when
requesting such operations to be done.
OPTIONS FILE
The file /etc/default/ejabberd contains specific options. Two of them are 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@hostname.domainname.
FIREWALL_WINDOW
Use the specified range of ports to communicate with the other Erlang nodes (namely, with the
target Erlang node running ejabberd). This can be useful when the system running the target node
has restricted firewall setup allowing only a certain range of ports to be used by the Erlang
nodes for communication; in this case, you should specify that range of ports in the
FIREWALL_WINDOW setting.
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@nes.ru> for the Debian system (but may be used
by others) from the ejabberd documentation written by Alexey Shchepin <alexey@sevcom.net>. Updated by
Konstantin Khomoutov <flatworm@users.sourceforge.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.
Version 2.1.0 RC1 04 October 2009 ejabberdctl(8)