.TH ejabberdctl 8 "04 October 2009" "Version 2.1.0 RC1" "ejabberdctl manual page"

.SH NAME
ejabberdctl \(em a control interface of ejabberd Jabber/XMPP server

.SH SYNOPSIS
.PP 
\fBejabberdctl\fR \fI[\-\-node nodename] [\-\-auth user host password] [command [options]]\fP

.SH DESCRIPTION
.PP 
\fBejabberdctl\fR  is a front end to the ejabberd Jabber/XMPP server.
It is designed to help the administrator control the functioning of the
running \fBejabberd\fR daemon.
.PP
This command must be run either by a superuser or by the user \fBejabberd\fP,
otherwise it will fail to start or to connect to the ejabberd instance.

.SH OPTIONS
.TP
.BI \-\-node " nodename"
Specifies remote Erlang node to connect to. Default value is
\fIejabberd\fP.
If the node name does not contain a symbol \fI@\fP
then the actual node name becomes \fInode@host\fP where \fIhost\fP is short
hostname (usually it coincides with \fI\(gahostname \-s\(ga\fP).
If the node name contains a symbol \fI@\fR and its hostname part
is a FQDN then \fBejabberd\fR will use so-called long names
(see \fBerl\fR(1) manual page and look for options \fI\-name\fP
and \fI\-sname\fP for details).

Examples of \fI\-\-node\fP option:

.BI ejabberd
Connect to locally run ejabberd server at node \fIejabberd@\(gahostname \-s\(ga\fP.

.BI ejabberd@otherhost
Connect to remotely run ejabberd server at node \fIejabberd@otherhost\fP.

.BI ejabberd@localhost
Connect to locally run ejabberd server at node \fIejabberd@localhost\fP.

ejabberdctl honors \fBERLANG_NODE\fR environment variable from
/etc/default/ejabberd, see below.

.TP
.BI \-\-auth " user host password"
If restriction of access to \fBejabberdctl\fR 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.
\fIuser\fP and \fIhost\fP are the respective parts of the entity JID
and \fIpassword\fP is either a plain text password to authenticate
that JID or the MD5 hash of that password.

.TP
.BI \-\-concurrent
Due to the way \fBejabberdctl\fR is implemented, it is normally not
possible to run two instances of it in parallel\(enthe second one
will fail.
This is OK in a common case when \fBejabberdctl\fR is only
run manually from time to time by a server administrator; if, conversely,
there is a chance for several instances of \fBejabberdctl\fR to be active
at the same time (say, automated registration of new users on an actively
used site), you can pass the \fI\-\-concurrent\fP option to
\fBejabberdctl\fR which will ensure no clash will ever occur.
.IP
Usage of the \fI\-\-concurrent\fP 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
.IP
Note that the semantics of this option can be changed in a future release.

.SH COMMANDS

.PP
Some commands to \fBejabberdctl\fR are single words, like \fBstatus\fR,
and some are multi-word, like \fBreopen-log\fR; 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: \fBstatus_list_host\fR, \fBstatus-list-host\fR,
\fBstatus_list-host\fR.

.PP
When run without any \fIcommand\fP specified, \fBejabberdctl\fR
prints the list of available commands and their short descriptions.

.PP
The following commands can be used:
.TP
.BI help " [\-\-tags [tag] | PATTERN]"
The \fBhelp\fR command without any options does the same thing
as running \fBejabberdctl\fR without any command specified \(em it
prints the list of available commands along with their short descriptions.
.IP
The \fI\-\-tags\fP option specified alone makes the \fBhelp\fR command
print the list of supported "help tags" which group \fBejabberdctl\fR
commands on the basis of their purpose (such as debugging commands,
backup commands etc).
.IP
The \fI\-\-tags\fP option specified with a tag \fItag\fP makes the
\fBhelp\fR command print the list of commands associated wih
the help tag \fItag\fP along with their short descriptions.
.IP
If the \fBhelp\fR 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 \fBejabberdctl\fR with this form of the
\fBhelp\fR command from the shell, you have to protect the characters
in the pattern from being interpreted by the shell.
.TP
.BI 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>.
.TP
.BI status
Request status of the Erlang virtual machine where ejabberd server is running.
.TP
.BI stop
Stop the ejabberd server and its Erlang virtual machine.
.TP
.BI stop-kindly " delay announcement"
Broadcast an announcement \fIannouncement\fP to all connected
users, wait \fIdelay\fP seconds and then stop the ejabberd server and
its Erlang virtual machine.
.IP
This command is interactive: it dumps the progress of the shutdown
sequence to stdout (including waiting for the grace period to pass).
.IP
The \fIannouncement\fP string is unconditionally interpreted as
a sequence of UTF-8 characters no matter what locale settings
the server and ejabberdctl processes see.
.TP
.BI 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.
.TP
.BI reopen\-log
Force the ejabberd server to reopen its log
files (\fI/var/log/ejabberd/ejabberd.log\fP and
\fI/var/log/erlang.log\fP by default).
If module mod_http_fileserver is loaded then force the ejabberd server to reopen
its weblog file.
.TP
.BI register " user server password"
Register user \fIuser\fP with password \fIpassword\fP at ejabberd virtual
host \fIserver\fP.
.TP
.BI unregister " user server"
Unregister user \fIuser\fP at ejabberd virtual host \fIserver\fP.
.TP
.BI backup " filepath"
Backup user database of the ejabberd server to file \fIfilepath\fP.
.IP
The directory in which \fIfilepath\fP is located must be writable
by the user "ejabberd".
.TP
.BI restore " filepath"
Restore user database of the ejabberd server from backup file \fIfilepath\fP.
.IP
The file \fIfilepath\fP must be readable by the user "ejabberd".
.TP
.BI install\-fallback " filepath"
Install a backup to \fIfilepath\fP as fallback. The fallback will be
used to restore the database at the next start-up.
.IP
The directory in which \fIfilepath\fP is located must be writable
by the user "ejabberd".
.TP
.BI dump " filepath"
Dump user database of the ejabberd server to text file \fIfilepath\fP.
.IP
The directory in which \fIfilepath\fP is located must be writable
by the user "ejabberd".
.TP
.BI load " filepath"
Restore user database of the ejabberd server from text file \fIfilepath\fP.
.IP
The file \fIfilepath\fP must be readable by the user "ejabberd".
.TP
.BI dump\-table " file table"
Dump the specified database \fItable\fR to the specified text \fIfile\fR.
.IP
The directory in which \fIfile\fP is located must be writable
by the user "ejabberd".
.TP
.BI import\-file " filepath"
Import user data from jabberd 1.4 spool file \fIfilepath\fP. For example, if
\fIfilepath\fP is \fI.../example.org/user.xml\fP then imported username will be
\fIuser\fP and it will be imported to virtual server \fIexample.org\fP.
.IP
The file \fIfilepath\fP must be readable by the user "ejabberd".
.TP
.BI import\-dir " directorypath"
Import user data from jabberd 1.4 spool directory \fIdirectorypath\fP. Directory
name should be the name of virtual server to import users.
.IP
The directory \fIdirectorypath\fP and the files in it must be readable
by the user "ejabberd".
.TP
.BI mnesia\-change\-nodename " oldnodename newnodename oldbackup newbackup"
Reads the backup file \fIoldbackup\fR (which should have been created
using the \fBejabberdctl backup\fR command) and writes its contents
to the file \fInewbackup\fR while replacing in it all occurences of the
Erlang node name \fIoldnodename\fR with the \fInewnodename\fR.
.IP
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.
.TP
.BI 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".
.IP
Note that ejabberd automatically runs this command if you update from
an ejabberd release 2.0.5 or older.
.IP
Running this command on already updated database does nothing.
.TP
.BI delete\-expired\-messages
Delete expired offline messages from ejabberd database.
.TP
.BI delete\-old\-messages " n"
Delete offline messages older than \fIn\fP days from ejabberd database.
.TP
.BI mnesia " info"
Show some information about the Mnesia system (see \fBmnesia\fP(3), function
\fIinfo\fP).
.TP
.BI mnesia
Show all information about the Mnesia system, such as transaction statistics,
database nodes, and configuration parameters (see \fBmnesia\fP(3), function
system_info).
.TP
.BI mnesia " key"
Show information about the Mnesia system according to \fIkey\fP specified
(see \fBmnesia\fP(3), function system_info for valid \fIkey\fP values).
.TP
.BI incoming\-s2s\-number
Print number of incoming server-to-server connections to the node.
.TP
.BI outgoing\-s2s\-number
Print number of outgoing server-to-server connections from the node.
.TP
.BI user\-resources " user server"
List all connected resources of user \fIuser@server\fP.
.TP
.BI connected\-users\-number
Report number of established users' sessions.
.TP
.BI connected\-users
Print full JIDs of all established sessions, one on a line.
.TP
.BI 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).
.TP
.BI connected\-users\-vhost " server"
Print full JIDs of all users registered at the virtual host \fIserver\fP
which are currently connected to the ejabberd server, one on a line.
.TP
.BI registered\-users " server"
List all the users registered on the ejabberd server
at the virtual host \fIserver\fP.
.TP
.BI get\-loglevel
Print the log level (an integer number) ejabberd is operating on.

.SS EXPORTING DATA TO PIEFXIS (XEP-0227) FORMAT

.PP
The commands described in this section require availability of the
\fBexmpp\fR library which is not shipped with ejabberd.
Your can download its source code from \fIhttp://exmpp.org\fP.

.TP
.BI 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 \fIdir\fR.
.IP
The directory \fIdir\fR must be writable by the user "ejabberd".
.TP
.BI export\-piefxis\-host " dir host"
Export data of all the users registered on the specified
virtual host \fIhost\fR to a set of PIEFXIS files
which will be stored in the directory \fIdir\fR.
.IP
The directory \fIdir\fR and the files in it must be readable
by the user "ejabberd".
.TP
.BI import\-piefxis " file"
Import users' data from a PIEFXIS file \fIfile\fR.
.IP
The file \fIfile\fR must be readable by the user "ejabberd".

.SH EXTRA OPTIONS
.PP
An optional module \fBmod_admin_extra\fP adds a number of other commands.
.PP
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).
.PP
To enable these additional commands add mod_admin_extra to the
\fB{modules}\fP section of ejabberd config file and make it
looking as the following:
.sp
.nf
{modules,
 [
  ...
  {mod_admin_extra, []},
  ...
 ]}.
.fi

.PP
Most of additional commands possess extended descriptions
which can be printed using
\fBejabberdctl help\fR \fIcommand\fP

.PP
The new commands are:

.TP
.BI add\-rosteritem " localuser localserver user server nick group subscription"
Add to the roster of the user \fIlocaluser\fP
registered on the virtual host \fIlocalserver\fP
a new entry for the user \fIuser\fP on the server \fIserver\fP,
assign the nickname \fInick\fP to it,
place this entry to the group \fIgroup\fP
and set its subscription type to \fIsubscription\fP
which is one of "none", "from", "to" or "both".

.TP
.BI delete\-rosteritem " localuser localserver user server"
Delete from the roster of the user \fIlocaluser\fP on the server
\fIlocalserver\fP an entry for the JID \fIuser\fP@\fIserver\fP.

.TP
.BI ban\-account " user host reason"
Ban the user \fIuser\fP registered on the virtual host \fIhost\fP.
This is done by kicking their active sessions with the reason
\fIreason\fP and replacing their password with a randomly
generated one.

.TP
.BI kick\-session " user host resource reason"
Kick the session opened by the user \fIuser\fP registered
on the virtual host \fIhost\fP
and having the resource \fIresource\fP bound to it
providing the reason \fIreason\fP.

.TP
.BI change\-password " user host newpass"
Change password of the user \fIuser\fP registered on the
virtual host \fIhost\fP to \fInewpass\fP.

.TP
.BI check\-account " user host"
Exit with code 0 if the user \fIuser\fP is registered
on the virtual host \fIhost\fP,
exit with code 1 otherwise.

.TP
.BI check\-password " user host password"
Exit with code 0 the user \fIuser\fP registered on the
virtual host \fIhost\fP has password \fIpassword\fP,
exit with code 1 otherwise.

.TP
.BI check\-password\-hash " user host passwordhash hashmethod"
Exit with code 0 if the user \fIuser\fP registered on the
virtual host \fIhost\fP has a password, the hash of which,
calculated using the \fIhashmethod\fP is equal
to the hash \fIpasswordhash\fP;
exit with code 1 otherwise.
.IP
Allowed hashing methods are "md5" and "sha" (for SHA-1).

.TP
.BI compile " file"
Compile and reload the Erlang source code file \fIfile\fP.
.IP
The file \fIfile\fR must be readable by the user "ejabberd".

.TP
.BI load\-config " file"
Load ejabberd configuration from the file \fIfile\fP.
.IP
The file \fIfile\fR must be readable by the user "ejabberd".
.IP
Note that loading config to a database does not mean
reloading the server \(em 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.

.TP
.BI delete\-old\-users " days"
Delete accounts and all related data of users who did not
log on the server for \fIdays\fP days.

.TP
.BI delete\-old\-users\-vhost " host days"
Delete accounts and all related data of users
registered on the virtual host \fIhost\fP
who did not log on the server for \fIdays\fP days.

.TP
.BI export2odbc " host path"
Export Mnesia database tables keeping the data for the virtual
host \fIhost\fP to a set of text files created under
the specified directory \fIpath\fP, which must exist and must be
writable by the user "ejabberd".

.TP
.BI get\-cookie
Print the cookie used by the Erlang node which runs ejabberd
instance \fBejabberdctl\fR controls.

.TP
.BI get\-roster " user host"
Print the roster of the user \fIuser\fP registered
on the virtual host \fIhost\fP.
.IP
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.

.TP
.BI push\-roster " file user host"
Push items from the file \fIfile\fP to the roster
of the user \fIuser\fP
registered on the virtual host \fIhost\fP.
.IP
The format of file containing roster items is the same
as used for output by the \fBget\-roster\fR command.

.TP
.BI push\-roster\-all " file"
.IP
The format of file containing roster items is the same
as used for output by the \fBget\-roster\fR command.

.TP
.BI push\-alltoall " host group"
All entries for all the users registered on the virtual host \fIhost\fP
to the rosters of all the users registered on this virtual host.
The created entries are assigned to the roster group \fIgroup\fP.

.TP
.BI process\-rosteritems " action subs asks users contacts"
\fBFIXME\fP no information available. Do not use.

.TP
.BI get\-vcard " user host name"
Print the contents of the field \fIname\fP
of a vCard belonging to the user \fIuser\fP
registered on the virtual host \fIhost\fP.
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).
.IP
For example \fIname\fP 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).

.TP
.BI get\-vcard2 " user host name subname"
Print the contents of the subfield \fIsubname\fP
of the field \fIname\fP
of a vCard belonging to the user \fIuser\fP
registered on the virtual host \fIhost\fP.
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).

.TP
.BI set\-vcard " user host name content"
Set the field \fIname\fP to the string \fIcontent\fP
in the vCard of the user \fIuser\fP
registered on the virtual host \fIhost\fP.

.TP
.BI set\-vcard2 " user host name subname content"
Set the subfield \fIsubname\fP
of the field \fIname\fP to the string \fIcontent\fP
in the vCard of the user \fIuser\fP
registered on the virtual host \fIhost\fP.

.TP
.BI set\-nickname " user host nickname"
Set the "nickname" field in the vCard of the user \fIuser\fP
registered on the virtual host \fIhost\fP to \fInickname\fP.

.TP
.BI num\-active\-users " host days"
Print number of users registered on the virtual host \fIhost\fP
who logged on the server at least once during the last
\fIdays\fP days.

.TP
.BI num\-resources " user host"
Print the number of resources (that is, active sessions)
the user \fIuser\fP registered on the virtual host \fIhost\fP
currently has.
If the specified user has no active sessions,
print the string "0".

.TP
.BI resource\-num " user host num"
Print the resource of a session number \fInum\fP
the user \fIuser\fP registered on the virtual host \fIhost\fP
has currently open.
\fInum\fP must be a positive integer, greater than or equal to 1.
.IP
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.

.TP
.BI remove\-node " node"
Remove the Erlang node \fInode\fP from the Mnesia
database cluster.

.TP
.BI send\-message\-chat " from to body"
Send a message of type "chat" from the JID \fIfrom\fP
to the (local or remote) JID \fIto\fP containing
the body \fIbody\fP.
Both bare and full JIDs are supported.

.TP
.BI send\-message\-headline " from to subject body"
Send a message of type "headline" from the JID \fIfrom\fP
to the (local or remote) JID \fIto\fP containing
the body \fIbody\fP and subject \fIsubject\fP.
Both bare and full JIDs are supported.

.TP
.BI send\-stanza\-c2s " user server resource stanza"
Send XML string \fIstanza\fP to the stream to which the
session \fIuser@server/resource\fP is bound.
The stanza must be well-formed (according to RFC 3920)
and the session must be active.
.IP
For example:
.nf
ejabberdctl send-stanza-c2s john_doe example.com Bahamas \\
  '<message id="1" type="chat"><body>How goes?</body></message>'
.fi

.TP
.BI srg\-create " group host name description display"
Create a new shared roster group \fIgroup\fP
on the virtual host \fIhost\fP
with displayed name \fIname\fP,
description \fIdescription\fP and displayed groups \fIdisplay\fP.

.TP
.BI srg\-delete " group host"
Delete the shared roster group \fIgroup\fP
from the virtual host \fIhost\fP.

.TP
.BI srg\-user\-add " user server group host"
Add an entry for the JID \fIuser\fP@\fIserver\fP
to the group \fIgroup\fP on the virtual host \fIhost\fP.

.TP
.BI srg\-user\-del " user server group host"
Delete an entry for the JID \fIuser\fP@\fIserver\fP
from the group \fIgroup\fP on the virtual host \fIhost\fP.

.TP
.BI srg\-list " host"
List the shared roster groups on the virtual host \fIhost\fP.

.TP
.BI srg\-get\-info " group host"
Print info on the shared roster group \fIgroup\fP
on the virtual host \fIhost\fP.

.TP
.BI srg\-get\-members " group host"
Print members of the shared roster group \fIgroup\fP
on the virtual host \fIhost\fP.

.TP
.BI 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
.nf
<\fIelement\fP xmlns="\fInamespace\fP"/>
.fi
payload from \fIuser@server\fP.
.IP
For example:
.nf
ejabberdctl private-get john_doe example.com \\
  storage storage:bookmarks
.fi
would return user's bookmarks, managed according to XEP-0048.

.TP
.BI private\-set " user server element"
Allows one to simulate \fIuser@server\fP sending an IQ-request
of type "set" containing \fIelement\fP as its payload;
the payload is processed by the code managing users' private storage
(XEP-0049 "Private XML Storage").
.IP
The string \fIelement\fP must be a well-formed XML obeying the
rules defined for IQ-request payloads in RFC 3920.

.TP
.BI privacy\-set " user server element"
Allows one to simulate \fIuser@server\fP sending an IQ-request
of type "set" containing \fIelement\fP as its payload;
this payload is processed by the code managing privacy lists
(XEP-0016 "Privacy lists").
.IP
The string \fIelement\fP must be a well-formed XML obeying the
rules defined for IQ-request payloads in RFC 3920.

.TP 
.BI stats " topic"
Print statistics on the topic \fItopic\fP.
The valid topics and their meaning are:
.IP
.BI registeredusers
Print the number of users registered on the server.
.IP
.BI onlineusers
Print the number of users currently logged into the server.
.IP
.BI onlineusersnode
Print the number of users logged into the server
which are served by the current ejabberd Erlang node.
.IP
.BI uptimeseconds
Print the uptime of the current ejabberd Erlang node, in seconds.

.TP
.BI stats\-host " host topic"
Print statistics on the topic \fItopic\fP
for the virtual host \fIhost\fP.
The valid topics and their meaning are:
.IP
.BI registeredusers
Print the number of users registered on the host \fIhost\fP.
.IP
.BI onlineusers
Print the number of users currently logged into the server,
which are registered on the host \fIhost\fP.

.TP
.BI status\-list " status"
Print the users currently logged into the server
and having the presence status \fIstatus\fP.
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.
.IP
The \fIstatus\fP parameter can take the following values:
"available", "away", "xa", "dnd" and "chat".

.TP
.BI status\-list\-host " host status"
Print the users currently logged into the server
which are registered on the virtual host \fIhost\fP
and have the presence status \fIstatus\fP.
.IP
The available values for the \fIstatus\fP parameter
and the format of the output data are the same
as of the \fBstatus\-list\fR subcommand.

.TP
.BI status\-num " status"
Print the number of users currently logged into the server
and having the presence status \fIstatus\fP.
.IP
The available values for the \fIstatus\fP parameter
are the same as of the \fBstatus\-list\fR subcommand.

.TP
.BI status\-num\-host " host status"
Print the number of users currently logged into the server
which are registered on the virtual host \fIhost\fP
and have the presence status \fIstatus\fP.
.IP
The available values for the \fIstatus\fP parameter
are the same as of the \fBstatus\-list\fR subcommand.

.TP
.BI user\-sessions\-info " user server"
Print detailed information on all sessions currently established
by \fIuser@server\fP.
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.

\" .TP
\" .BI muc\-purge " days"
\" Destroy MUC rooms with zero activity (no messages in history) in the last
\" \fIdays\fP days.
\" .TP
\" .BI muc\-online\-rooms
\" Print the list of existing MUC rooms.

\" entries related to mod_ctlextra (2.0.x series):

\".TP
\".BI pushroster " file user server"
\"Push template roster in file \fIfile\fP to \fIuser@server\fP. The file contents
\"must use the following format:
\".sp
\".nf
\"[{"bob", "example.org", "Bob's group", "Bob's nickname"},
\" {"mart", "example.org", "workers", "Mart"},
\" {"Rich", "example.org", "bosses", "Rich"}].
\".fi
\".TP
\".BI pushroster\-all " file"
\"Push template roster in file to all users listed in the file \fIfile\fP itself.
\"The file contents must be in the same format as for \fBpushroster\fP command.

.SH NOTES

.PP
\fBejabberdctl\fR starts distributed Erlang node \fIejabberddebug\fP (if run
with \fBdebug\fP option) or \fIejabberdctl\fP (if run with any other options).
If the ejabberd server's node name to connect to includes FDQN as a hostname
Erlang option \fI\-name\fP is used. Otherwise \fBejabberdctl\fR uses short
names (\fI\-sname\fP option).

.PP
Note that \fBejabberdctl\fR does not append hostname to its own node name
leaving this to Erlang emulator. It usually follows \fI\(gahostname \-f\(ga\fP
to find a hostname if long names are used or \fI\(gahostname \-s\(ga\fP in
case of short names, but may fail in case of unusual networking settings. A
known case of failure is using long names when \fI\(gahostname \-f\(ga\fP
doesn't return FDQN. If \fRejabberdctl\fR cannot create Erlang node then it
cannot control ejabberd server.

.PP
\fBejabberdctl\fR 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 \fBejabberdctl\fR'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.

.SH OPTIONS FILE
.PP 
The file \fB/etc/default/ejabberd\fR contains specific options. Two of them
are used by \fBejabberdctl\fP.

.TP
.BI ERLANG_NODE
Use specified string as Erlang node of \fBejabberd\fP server to connect. It
overrides default \fBejabberd\fP node name. The string may take one of the
following forms: \fBnodename\fP, \fBnodename@hostname\fP or
\fBnodename@hostname.domainname\fP.

.TP
.BI 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 \fBFIREWALL_WINDOW\fR setting.

.SH FILES
.PD 0
.I /etc/default/ejabberd
default variables

.SH SEE ALSO 
.PP 
\fBerl\fR(1), \fBejabberd\fR(8), \fBmnesia\fR(3).

.PP 
The program documentation is available at
\fIhttp://www.process\-one.net/en/projects/ejabberd/\fP. 
A copy of the documentation can be found at
/usr/share/doc/ejabberd/guide.html.
 
.SH AUTHORS
.PP 
This manual page was adapted by Sergei Golovan <sgolovan@nes.ru> for 
the \fBDebian\fP system (but may be used by others) from the
\fBejabberd\fP 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. 
.PP 
On Debian systems, the complete text of the GNU General Public 
License can be found in /usr/share/common\-licenses/GPL.