Provided by: ejabberd_16.01-2_i386 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.