Man Linux: Main Page and Category List

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

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.