Section: ejabberdctl manual page (8)Updated: 04 October 2009Local indexUp
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`.
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".
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.
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 helpcommand
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.
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.
would return user's bookmarks, managed according to XEP-0048.
private-set user server element
Allows 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 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.
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.