Provided by: ejabberd_2.1.10-2ubuntu1_amd64 bug

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.