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.
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".
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.