842 lines
31 KiB
HTML
842 lines
31 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
|
|
"http://www.w3.org/TR/REC-html40/loose.dtd">
|
|
<HTML>
|
|
<HEAD><TITLE>Ejabberd Installation and Operation Guide</TITLE>
|
|
|
|
<META http-equiv="Content-Type" content="text/html; charset=KOI8-R">
|
|
<META name="GENERATOR" content="hevea 1.06">
|
|
</HEAD>
|
|
<BODY >
|
|
<!--HEVEA command line is: /usr/bin/hevea guide.tex -->
|
|
<!--HTMLHEAD-->
|
|
<!--ENDHTML-->
|
|
<!--PREFIX <ARG ></ARG>-->
|
|
<!--CUT DEF section 1 -->
|
|
|
|
|
|
|
|
<H1 ALIGN=center>Ejabberd Installation and Operation Guide</H1>
|
|
|
|
<H3 ALIGN=center>Alexey Shchepin<BR>
|
|
<A HREF="mailto:alexey@sevcom.net"><TT>mailto:alexey@sevcom.net</TT></A><BR>
|
|
<A HREF="xmpp:aleksey@jabber.ru"><TT>xmpp:aleksey@jabber.ru</TT></A></H3>
|
|
|
|
<H3 ALIGN=center>July 12, 2003</H3><DIV ALIGN=center>
|
|
|
|
<IMG SRC="logo.png">
|
|
|
|
|
|
</DIV><BR>
|
|
<BR>
|
|
|
|
|
|
<!--TOC section Table of Contents-->
|
|
|
|
<H2>Table of Contents</H2><!--SEC END -->
|
|
|
|
<UL><LI>
|
|
<A HREF="#htoc1">1 Introduction</A>
|
|
<LI><A HREF="#htoc2">2 Installation</A>
|
|
<UL><LI>
|
|
<A HREF="#htoc3">2.1 Installation Requirements</A>
|
|
<UL><LI>
|
|
<A HREF="#htoc4">2.1.1 Unix</A>
|
|
<LI><A HREF="#htoc5">2.1.2 Windows</A>
|
|
</UL>
|
|
<LI><A HREF="#htoc6">2.2 Obtaining</A>
|
|
<LI><A HREF="#htoc7">2.3 Compilation</A>
|
|
<UL><LI>
|
|
<A HREF="#htoc8">2.3.1 Unix</A>
|
|
<LI><A HREF="#htoc9">2.3.2 Windows</A>
|
|
</UL>
|
|
<LI><A HREF="#htoc10">2.4 Starting</A>
|
|
</UL>
|
|
<LI><A HREF="#htoc11">3 Configuration</A>
|
|
<UL><LI>
|
|
<A HREF="#htoc12">3.1 Initial Configuration</A>
|
|
<UL><LI>
|
|
<A HREF="#htoc13">3.1.1 Host Name</A>
|
|
<LI><A HREF="#htoc14">3.1.2 Access Rules</A>
|
|
<LI><A HREF="#htoc15">3.1.3 Shapers Configuration</A>
|
|
<LI><A HREF="#htoc16">3.1.4 Listened Sockets</A>
|
|
<LI><A HREF="#htoc17">3.1.5 Modules</A>
|
|
</UL>
|
|
<LI><A HREF="#htoc18">3.2 Online Configuration and Monitoring</A>
|
|
<UL><LI>
|
|
<A HREF="#htoc19">3.2.1 Node <TT>config</TT>: Global Configuration</A>
|
|
<LI><A HREF="#htoc20">3.2.2 Node <TT>online users</TT>: List of Online Users</A>
|
|
<LI><A HREF="#htoc21">3.2.3 Node <TT>all users</TT>: List of Registered User</A>
|
|
<LI><A HREF="#htoc22">3.2.4 Node <TT>outgoing s2s</TT>: List of Outgoing S2S connections</A>
|
|
<LI><A HREF="#htoc23">3.2.5 Node <TT>running nodes</TT>: List of Running <TT>ejabberd</TT> Nodes</A>
|
|
<LI><A HREF="#htoc24">3.2.6 Node <TT>stopped nodes</TT>: List of Stopped Nodes</A>
|
|
</UL>
|
|
</UL>
|
|
<LI><A HREF="#htoc25">4 Distribution</A>
|
|
<UL><LI>
|
|
<A HREF="#htoc26">4.1 How it works</A>
|
|
<UL><LI>
|
|
<A HREF="#htoc27">4.1.1 Router</A>
|
|
<LI><A HREF="#htoc28">4.1.2 Local Router</A>
|
|
<LI><A HREF="#htoc29">4.1.3 Session Manager</A>
|
|
<LI><A HREF="#htoc30">4.1.4 S2S Manager</A>
|
|
</UL>
|
|
</UL>
|
|
<LI><A HREF="#htoc31">A Built-in Modules</A>
|
|
<UL><LI>
|
|
<A HREF="#htoc32">A.1 Common Options</A>
|
|
<UL><LI>
|
|
<A HREF="#htoc33">A.1.1 Option <TT>iqdisc</TT></A>
|
|
<LI><A HREF="#htoc34">A.1.2 Option <TT>host</TT></A>
|
|
</UL>
|
|
<LI><A HREF="#htoc35">A.2 <TT>mod_register</TT></A>
|
|
<LI><A HREF="#htoc36">A.3 <TT>mod_roster</TT></A>
|
|
<LI><A HREF="#htoc37">A.4 <TT>mod_configure</TT></A>
|
|
<LI><A HREF="#htoc38">A.5 <TT>mod_disco</TT></A>
|
|
<LI><A HREF="#htoc39">A.6 <TT>mod_stats</TT></A>
|
|
<LI><A HREF="#htoc40">A.7 <TT>mod_vcard</TT></A>
|
|
<LI><A HREF="#htoc41">A.8 <TT>mod_offline</TT></A>
|
|
<LI><A HREF="#htoc42">A.9 <TT>mod_echo</TT></A>
|
|
<LI><A HREF="#htoc43">A.10 <TT>mod_private</TT></A>
|
|
<LI><A HREF="#htoc44">A.11 <TT>mod_time</TT></A>
|
|
<LI><A HREF="#htoc45">A.12 <TT>mod_version</TT></A>
|
|
</UL>
|
|
<LI><A HREF="#htoc46">B I18n/L10n</A>
|
|
</UL>
|
|
|
|
<!--TOC section Introduction-->
|
|
|
|
<H2><A NAME="htoc1">1</A> Introduction</H2><!--SEC END -->
|
|
|
|
<A NAME="sec:intro"></A>
|
|
<TT>ejabberd</TT> is a Free and Open Source fault-tolerant distributed Jabber
|
|
server. It is writen mostly in Erlang.<BR>
|
|
<BR>
|
|
The main features of <TT>ejabberd</TT> is:
|
|
<UL><LI>
|
|
Works on most of popular platforms: *nix (tested on Linux and FreeBSD)
|
|
and Win32
|
|
<LI>Distributed: You may run <TT>ejabberd</TT> on a cluster of machines and all of
|
|
them will serve one Jabber domain.
|
|
<LI>Fault-tolerance: You may setup an <TT>ejabberd</TT> cluster so that all the
|
|
information required for a properly working service will be stored
|
|
permanently on more than one node. This means that if one of the nodes
|
|
crashes, then the others will continue working without disruption.
|
|
You can also add or replace more nodes ``on the fly''.
|
|
<LI>Built-in <A HREF="http://www.jabber.org/jeps/jep-0045.html">Multi-User
|
|
Chat</A> service
|
|
<LI>Built-in IRC transport
|
|
<LI>Built-in
|
|
<A HREF="http://www.jabber.org/jeps/jep-0060.html">Publish-Subscribe</A>
|
|
service
|
|
<LI>Built-in Jabber Users Directory service based on users vCards
|
|
<LI>Support for
|
|
<A HREF="http://www.jabber.org/jeps/jep-0030.html">JEP-0030</A>
|
|
(Service Discovery).
|
|
<LI>Support for
|
|
<A HREF="http://www.jabber.org/jeps/jep-0039.html">JEP-0039</A>
|
|
(Statistics Gathering).
|
|
<LI>Support for <TT>xml:lang</TT> attribute in many XML elements
|
|
</UL>
|
|
<!--TOC section Installation-->
|
|
|
|
<H2><A NAME="htoc2">2</A> Installation</H2><!--SEC END -->
|
|
|
|
<A NAME="sec:installation"></A>
|
|
<!--TOC subsection Installation Requirements-->
|
|
|
|
<H3><A NAME="htoc3">2.1</A> Installation Requirements</H3><!--SEC END -->
|
|
|
|
<A NAME="sec:installreq"></A>
|
|
<!--TOC subsubsection Unix-->
|
|
|
|
<H4><A NAME="htoc4">2.1.1</A> Unix</H4><!--SEC END -->
|
|
|
|
<A NAME="sec:installrequnix"></A>
|
|
To compile <TT>ejabberd</TT>, you will need the following packages:
|
|
<UL><LI>
|
|
GNU Make;
|
|
<LI>GCC;
|
|
<LI>libexpat 1.95 or later;
|
|
<LI>Erlang/OTP R8B or later.
|
|
</UL>
|
|
<!--TOC subsubsection Windows-->
|
|
|
|
<H4><A NAME="htoc5">2.1.2</A> Windows</H4><!--SEC END -->
|
|
|
|
<A NAME="sec:installreqwin"></A>
|
|
To compile <TT>ejabberd</TT> in MS Windows environment, you will need the following
|
|
packages:
|
|
<UL><LI>
|
|
MS Visual C++ 6.0 Compiler
|
|
<LI><A HREF="http://www.erlang.org/download/otp_win32_R8B-2.exe">Erlang
|
|
emulator version 5.1.2</A>
|
|
<LI><A HREF="http://prdownloads.sourceforge.net/expat/expat_win32bin_1_95_6.exe?download">Expat 1.95.6</A>
|
|
<LI><A HREF="http://prdownloads.sourceforge.net/gnuwin32/libiconv-1.8-1-lib.exe?download">Iconv 1.8</A> (optional)
|
|
</UL>
|
|
<!--TOC subsection Obtaining-->
|
|
|
|
<H3><A NAME="htoc6">2.2</A> Obtaining</H3><!--SEC END -->
|
|
|
|
<A NAME="sec:obtaining"></A>
|
|
Currently no stable version has been released.<BR>
|
|
<BR>
|
|
The latest alpha version can be retrieved from CVS.
|
|
<UL><LI>
|
|
<TT>export CVSROOT=:pserver:anonymous@jabberstudio.org:/home/cvs</TT>
|
|
<LI><TT>cvs login</TT>
|
|
<LI>Press Enter when asked for a password
|
|
<LI><TT>cvs -z3 co ejabberd</TT>
|
|
</UL>
|
|
<!--TOC subsection Compilation-->
|
|
|
|
<H3><A NAME="htoc7">2.3</A> Compilation</H3><!--SEC END -->
|
|
|
|
<A NAME="sec:compilation"></A>
|
|
<!--TOC subsubsection Unix-->
|
|
|
|
<H4><A NAME="htoc8">2.3.1</A> Unix</H4><!--SEC END -->
|
|
|
|
<A NAME="sec:compilationunix"></A>
|
|
<PRE>
|
|
./configure
|
|
make
|
|
</PRE>
|
|
TBD<BR>
|
|
<BR>
|
|
<!--TOC subsubsection Windows-->
|
|
|
|
<H4><A NAME="htoc9">2.3.2</A> Windows</H4><!--SEC END -->
|
|
|
|
<A NAME="sec:compilationwin"></A>
|
|
<OL type=1><LI>
|
|
Install Erlang emulator (for example, into <CODE>C:\Program Files\erl5.1.2</CODE>).
|
|
<LI>Install Expat library into <CODE>C:\Program Files\Expat-1.95.6</CODE>
|
|
directory. Copy file <CODE>C:\Program Files\Expat-1.95.6\Libs\libexpat.dll</CODE> to your Windows system directory (for
|
|
example, <CODE>C:\WINNT</CODE> or <CODE>C:\WINNT\System32</CODE>)
|
|
<LI>Install Iconv library into <CODE>C:\Program Files\GnuWin32</CODE> directory.
|
|
Copy file <CODE>C:\Program Files\GnuWin32\bin\libiconv-2.dll</CODE> to your
|
|
Windows system directory.<BR>
|
|
<BR>
|
|
Note: Instead of copying libexpat.dll and libiconv-2.dll to Windows
|
|
directory, you can add directories
|
|
<CODE>C:\Program Files\Expat-1.95.6\Libs</CODE> and
|
|
<CODE>C:\Program Files\GnuWin32\bin</CODE> to <CODE>PATH</CODE> environment
|
|
variable.
|
|
<LI>Being in <CODE>ejabberd\src</CODE> directory run:
|
|
<PRE>
|
|
configure
|
|
nmake -f Makefile.win32
|
|
</PRE><LI>To build MUC, IRC and pub/sub modules run
|
|
<PRE>
|
|
nmake -f Makefile.win32
|
|
</PRE>in <CODE>ejabberd\src\mod_muc</CODE>, <CODE>ejabberd\src\mod_muc</CODE> and
|
|
<CODE>ejabberd\src\mod_pubsub</CODE> directories
|
|
<LI>Edit file <CODE>ejabberd\src\ejabberd.cfg</CODE> and run
|
|
<PRE>
|
|
werl -s ejabberd -name ejabberd
|
|
</PRE><LI>Enjoy!
|
|
</OL>
|
|
<!--TOC subsection Starting-->
|
|
|
|
<H3><A NAME="htoc10">2.4</A> Starting</H3><!--SEC END -->
|
|
|
|
<A NAME="sec:starting"></A>
|
|
... To use more than 1024 connections, you will need to set environment
|
|
variable <TT>ERL_MAX_PORTS</TT>:
|
|
<PRE>
|
|
export ERL_MAX_PORTS=32000
|
|
</PRE>Note that with this value <TT>ejabberd</TT> will use more memory (approximately 6MB
|
|
more)...
|
|
<PRE>
|
|
erl -name ejabberd -s ejabberd
|
|
</PRE>
|
|
TBD<BR>
|
|
<BR>
|
|
<!--TOC section Configuration-->
|
|
|
|
<H2><A NAME="htoc11">3</A> Configuration</H2><!--SEC END -->
|
|
|
|
<A NAME="sec:configuration"></A>
|
|
<!--TOC subsection Initial Configuration-->
|
|
|
|
<H3><A NAME="htoc12">3.1</A> Initial Configuration</H3><!--SEC END -->
|
|
|
|
<A NAME="sec:initconfig"></A>
|
|
The configuration file is initially loaded the first time <TT>ejabberd</TT> is
|
|
executed, when it is parsed and stored in a database. Subsiquently the
|
|
configuration is loaded from the database and any commands in the configuration
|
|
file are appended to the entries in the database. The configuration file
|
|
consists of a sequence of Erlang terms. Parts of lines after <TT>`%'</TT> sign
|
|
are ignored. Each term is tuple, where first element is name of option, and
|
|
other are option values. E. g. if this file does not contain a ``host''
|
|
definition, then old value stored in the database will be used.<BR>
|
|
<BR>
|
|
To override old values stored in the database the following lines can be added
|
|
in config:
|
|
<PRE>
|
|
override_global.
|
|
override_local.
|
|
override_acls.
|
|
</PRE>With this lines old global or local options or ACLs will be removed before
|
|
adding new ones.<BR>
|
|
<BR>
|
|
<!--TOC subsubsection Host Name-->
|
|
|
|
<H4><A NAME="htoc13">3.1.1</A> Host Name</H4><!--SEC END -->
|
|
|
|
<A NAME="sec:confighostname"></A>
|
|
Option <TT>hostname</TT> defines name of Jabber domain that <TT>ejabberd</TT>
|
|
serves. E. g. to use <TT>jabber.org</TT> domain add following line in config:
|
|
<PRE>
|
|
{host, "jabber.org"}.
|
|
</PRE>
|
|
<!--TOC subsubsection Access Rules-->
|
|
|
|
<H4><A NAME="htoc14">3.1.2</A> Access Rules</H4><!--SEC END -->
|
|
|
|
<A NAME="sec:configaccess"></A>
|
|
Access control in <TT>ejabberd</TT> is performed via Access Control Lists (ACL). The
|
|
declarations of ACL in config file have following syntax:
|
|
<PRE>
|
|
{acl, <aclname>, {<acltype>, ...}}.
|
|
</PRE>
|
|
<TT><acltype></TT> can be one of following:
|
|
<DL COMPACT=compact><DT>
|
|
<B><TT>all</TT></B><DD> Matches all JIDs. Example:
|
|
<PRE>
|
|
{acl, all, all}.
|
|
</PRE><DT><B><TT>{user, <username>}</TT></B><DD> Matches local user with name
|
|
<TT><username></TT>. Example:
|
|
<PRE>
|
|
{acl, admin, {user, "aleksey"}}.
|
|
</PRE><DT><B><TT>{user, <username>, <server>}</TT></B><DD> Matches user with JID
|
|
<TT><username>@<server></TT> and any resource. Example:
|
|
<PRE>
|
|
{acl, admin, {user, "aleksey", "jabber.ru"}}.
|
|
</PRE><DT><B><TT>{server, <server>}</TT></B><DD> Matches any JID from server
|
|
<TT><server></TT>. Example:
|
|
<PRE>
|
|
{acl, jabberorg, {server, "jabber.org"}}.
|
|
</PRE><DT><B><TT>{user_regexp, <regexp>}</TT></B><DD> Matches local user with name that
|
|
matches <TT><regexp></TT>. Example:
|
|
<PRE>
|
|
{acl, tests, {user, "^test[0-9]*$"}}.
|
|
</PRE><DT><B><TT>{user_regexp, <regexp>, <server>}</TT></B><DD> Matches user with name
|
|
that matches <TT><regexp></TT> and from server <TT><server></TT>. Example:
|
|
<PRE>
|
|
{acl, tests, {user, "^test", "localhost"}}.
|
|
</PRE><DT><B><TT>{server_regexp, <regexp>}</TT></B><DD> Matches any JID from server that
|
|
matches <TT><regexp></TT>. Example:
|
|
<PRE>
|
|
{acl, icq, {server, "^icq\\."}}.
|
|
</PRE><DT><B><TT>{node_regexp, <user_regexp>, <server_regexp>}</TT></B><DD> Matches user
|
|
with name that matches <TT><user_regexp></TT> and from server that matches
|
|
<TT><server_regexp></TT>. Example:
|
|
<PRE>
|
|
{acl, aleksey, {node_regexp, "^aleksey", "^jabber.(ru|org)$"}}.
|
|
</PRE><DT><B><TT>{user_glob, <glob>}</TT></B><DD>
|
|
<DT><B><TT>{user_glob, <glob>, <server>}</TT></B><DD>
|
|
<DT><B><TT>{server_glob, <glob>}</TT></B><DD>
|
|
<DT><B><TT>{node_glob, <user_glob>, <server_glob>}</TT></B><DD> This is same as
|
|
above, but uses shell glob patterns instead of regexp. These patterns can
|
|
have following special characters:
|
|
<DL COMPACT=compact><DT>
|
|
<B><TT>*</TT></B><DD> matches any string including the null string.
|
|
<DT><B><TT>?</TT></B><DD> matches any single character.
|
|
<DT><B><TT>[...]</TT></B><DD> matches any of the enclosed characters. Character
|
|
ranges are specified by a pair of characters separated by a <TT>`-'</TT>.
|
|
If the first character after <TT>`['</TT> is a <TT>`!'</TT>, then any
|
|
character not enclosed is matched.
|
|
</DL>
|
|
</DL>
|
|
The following ACLs pre-defined:
|
|
<DL COMPACT=compact><DT>
|
|
<B><TT>all</TT></B><DD> Matches all JIDs.
|
|
<DT><B><TT>none</TT></B><DD> Matches none JIDs.
|
|
</DL>
|
|
An entry allowing or denying different services would look similar to this:
|
|
<PRE>
|
|
{access, <accessname>, [{allow, <aclname>},
|
|
{deny, <aclname>},
|
|
...
|
|
]}.
|
|
</PRE>When a JID is checked to have access to <TT><accessname></TT>, the server
|
|
sequentially checks if this JID mathes one of the ACLs that are second elements
|
|
in each tuple in list. If it is matched, then the first element of matched
|
|
tuple is returned else ``<TT>deny</TT>'' is returned.<BR>
|
|
<BR>
|
|
Example:
|
|
<PRE>
|
|
{access, configure, [{allow, admin}]}.
|
|
{access, something, [{deny, badmans},
|
|
{allow, all}]}.
|
|
</PRE>
|
|
Following access rules pre-defined:
|
|
<DL COMPACT=compact><DT>
|
|
<B><TT>all</TT></B><DD> Always return ``<TT>allow</TT>''
|
|
<DT><B><TT>none</TT></B><DD> Always return ``<TT>deny</TT>''
|
|
</DL>
|
|
<!--TOC subsubsection Shapers Configuration-->
|
|
|
|
<H4><A NAME="htoc15">3.1.3</A> Shapers Configuration</H4><!--SEC END -->
|
|
|
|
<A NAME="sec:configshaper"></A>
|
|
With shapers is possible to bound connection traffic. The declarations of
|
|
shapers in config file have following syntax:
|
|
<PRE>
|
|
{shaper, <shapername>, <kind>}.
|
|
</PRE>Currently implemented only one kind of shaper: <TT>maxrate</TT>. It have
|
|
following syntax:
|
|
<PRE>
|
|
{maxrate, <rate>}
|
|
</PRE>where <TT><rate></TT> means maximum allowed incomig rate in bytes/second.
|
|
E. g. to define shaper with name ``<TT>normal</TT>'' and maximum allowed rate
|
|
1000 bytes/s, add following line in config:
|
|
<PRE>
|
|
{shaper, normal, {maxrate, 1000}}.
|
|
</PRE>
|
|
<!--TOC subsubsection Listened Sockets-->
|
|
|
|
<H4><A NAME="htoc16">3.1.4</A> Listened Sockets</H4><!--SEC END -->
|
|
|
|
<A NAME="sec:configlistened"></A>
|
|
Option <TT>listen</TT> defines list of listened sockets and what services
|
|
runned on them. Each element of list is a tuple with following elements:
|
|
<UL><LI>
|
|
Port number;
|
|
<LI>Module that serves this port;
|
|
<LI>Function in this module that starts connection (likely will be removed in
|
|
future versions of <TT>ejabberd</TT>);
|
|
<LI>Options to this module.
|
|
</UL>
|
|
Currently three modules are implemented:
|
|
<DL COMPACT=compact><DT>
|
|
<B><TT>ejabberd_c2s</TT></B><DD> This module serves C2S connections.<BR>
|
|
<BR>
|
|
Following options defined:
|
|
<DL COMPACT=compact><DT>
|
|
<B><TT>{access, <access rule>}</TT></B><DD> This option defines access of users
|
|
to this C2S port. Default value is ``<TT>all</TT>''.
|
|
<DT><B><TT>{shaper, <access rule>}</TT></B><DD> This option is like previous, but
|
|
use shapers instead of ``<TT>allow</TT>'' and ``<TT>deny</TT>''. Default
|
|
value is ``<TT>none</TT>''.
|
|
</DL>
|
|
<DT><B><TT>ejabberd_s2s_in</TT></B><DD> This module serves incoming S2S connections.
|
|
<DT><B><TT>ejabberd_service</TT></B><DD> This module serves connections from Jabber
|
|
services (i. e. that use the <TT>jabber:component:accept</TT> namespace).
|
|
</DL>
|
|
For example, the following configuration defines that C2S connections are
|
|
listened on port 5222 and denied for user ``<TT>bad</TT>'', S2S on port 5269
|
|
and that service <TT>conference.jabber.org</TT> must be connected to port 8888
|
|
with a password ``<TT>secret</TT>''. Also all users except admins have traffic
|
|
limit 1000 b/s.
|
|
<PRE>
|
|
{acl, blocked, {user, "bad"}}.
|
|
{access, c2s, [{deny, blocked},
|
|
{allow, all}]}.
|
|
{shaper, normal, {maxrate, 1000}}.
|
|
{access, c2s_shaper, [{none, admin},
|
|
{normal, all}]}.
|
|
{listen, [{5222, ejabberd_c2s, start, [{access, c2s},
|
|
{shaper, c2s_shaper}]},
|
|
{5269, ejabberd_s2s_in, start, []},
|
|
{8888, ejabberd_service, start,
|
|
[{host, "conference.jabber.org", [{password, "secret"}]}]}
|
|
]}.
|
|
</PRE>
|
|
<!--TOC subsubsection Modules-->
|
|
|
|
<H4><A NAME="htoc17">3.1.5</A> Modules</H4><!--SEC END -->
|
|
|
|
<A NAME="sec:configmodules"></A>
|
|
Option <TT>modules</TT> defines the list of modules that will be loaded after
|
|
<TT>ejabberd</TT> startup. Each list element is a tuple where first element is a
|
|
name of a module and second is list of options to this module. See
|
|
section <A HREF="#sec:modules">A</A> for detailed information on each module.<BR>
|
|
<BR>
|
|
Example:
|
|
<PRE>
|
|
{modules, [
|
|
{mod_register, []},
|
|
{mod_roster, []},
|
|
{mod_configure, []},
|
|
{mod_disco, []},
|
|
{mod_stats, []},
|
|
{mod_vcard, []},
|
|
{mod_offline, []},
|
|
{mod_echo, [{host, "echo.localhost"}]},
|
|
{mod_private, []},
|
|
{mod_time, [{iqdisc, no_queue}]},
|
|
{mod_version, []}
|
|
]}.
|
|
</PRE>
|
|
<!--TOC subsection Online Configuration and Monitoring-->
|
|
|
|
<H3><A NAME="htoc18">3.2</A> Online Configuration and Monitoring</H3><!--SEC END -->
|
|
|
|
<A NAME="sec:onlineconfig"></A>
|
|
To perform online reconfiguration of <TT>ejabberd</TT> you will need to have
|
|
<TT>mod_configure</TT> loaded (see section <A HREF="#sec:modconfigure">A.4</A>). It is also highly
|
|
recommended to load <TT>mod_disco</TT> as well (see section <A HREF="#sec:moddisco">A.5</A>),
|
|
because <TT>mod_configure</TT> is highly integrated with it. Additionally it is
|
|
recommended to use a disco- and xdata-capable client such as
|
|
<A HREF="http://www.jabber.ru/projects/tkabber/index_en.html">Tkabber</A>
|
|
(which was developed synchronously with <TT>ejabberd</TT>, its CVS version
|
|
supports most of <TT>ejabberd</TT> features).<BR>
|
|
<BR>
|
|
On disco query <TT>ejabberd</TT> returns following items:
|
|
<UL><LI>
|
|
Identity of server.
|
|
<LI>List of features, including defined namespaces.
|
|
<LI>List of JIDs from route table.
|
|
<LI>List of disco-nodes described in following subsections.
|
|
</UL>
|
|
<BLOCKQUOTE><DIV ALIGN=center><DIV ALIGN=center><HR WIDTH="80%" SIZE=2></DIV>
|
|
|
|
<IMG SRC="disco.png">
|
|
|
|
|
|
<BR>
|
|
<DIV ALIGN=center>Figure 1: Tkabber Discovery window</DIV><BR>
|
|
|
|
<A NAME="fig:disco"></A>
|
|
<DIV ALIGN=center><HR WIDTH="80%" SIZE=2></DIV></DIV></BLOCKQUOTE>
|
|
<!--TOC subsubsection Node <TT>config</TT>: Global Configuration-->
|
|
|
|
<H4><A NAME="htoc19">3.2.1</A> Node <TT>config</TT>: Global Configuration</H4><!--SEC END -->
|
|
|
|
Under this node the following nodes exists:<BR>
|
|
<BR>
|
|
<!--TOC paragraph Node <TT>config/hostname</TT>-->
|
|
|
|
<H5>Node <TT>config/hostname</TT></H5><!--SEC END -->
|
|
|
|
Via <TT>jabber:x:data</TT> queries to this node possible to change host name of
|
|
this <TT>ejabberd</TT> server. (See figure <A HREF="#fig:hostname">2</A>) (Currently this works
|
|
correctly only after a restart)
|
|
<BLOCKQUOTE><DIV ALIGN=center><DIV ALIGN=center><HR WIDTH="80%" SIZE=2></DIV>
|
|
|
|
<IMG SRC="confhostname.png">
|
|
|
|
|
|
<BR>
|
|
<DIV ALIGN=center>Figure 2: Editing of hostname</DIV><BR>
|
|
|
|
<A NAME="fig:hostname"></A>
|
|
<DIV ALIGN=center><HR WIDTH="80%" SIZE=2></DIV></DIV></BLOCKQUOTE>
|
|
<!--TOC paragraph Node <TT>config/acls</TT>-->
|
|
|
|
<H5>Node <TT>config/acls</TT></H5><!--SEC END -->
|
|
|
|
Via <TT>jabber:x:data</TT> queries to this node it is possible to edit ACLs list.
|
|
(See figure <A HREF="#fig:acls">3</A>)
|
|
<BLOCKQUOTE><DIV ALIGN=center><DIV ALIGN=center><HR WIDTH="80%" SIZE=2></DIV>
|
|
|
|
<IMG SRC="confacls.png">
|
|
|
|
|
|
<BR>
|
|
<DIV ALIGN=center>Figure 3: Editing of ACLs</DIV><BR>
|
|
|
|
<A NAME="fig:acls"></A>
|
|
<DIV ALIGN=center><HR WIDTH="80%" SIZE=2></DIV></DIV></BLOCKQUOTE>
|
|
<!--TOC paragraph Node <TT>config/access</TT>-->
|
|
|
|
<H5>Node <TT>config/access</TT></H5><!--SEC END -->
|
|
|
|
Via <TT>jabber:x:data</TT> queries to this node it is possible to edit access
|
|
rules.<BR>
|
|
<BR>
|
|
<!--TOC paragraph Node <TT>config/remusers</TT>-->
|
|
|
|
<H5>Node <TT>config/remusers</TT></H5><!--SEC END -->
|
|
|
|
Via <TT>jabber:x:data</TT> queries to this node it is possible to remove users. If
|
|
removed user is online, then he will be disconnected. Also user-related data
|
|
(e.g. his roster) is removed (but appropriate module must be loaded).<BR>
|
|
<BR>
|
|
<!--TOC subsubsection Node <TT>online users</TT>: List of Online Users-->
|
|
|
|
<H4><A NAME="htoc20">3.2.2</A> Node <TT>online users</TT>: List of Online Users</H4><!--SEC END -->
|
|
|
|
<!--TOC subsubsection Node <TT>all users</TT>: List of Registered User-->
|
|
|
|
<H4><A NAME="htoc21">3.2.3</A> Node <TT>all users</TT>: List of Registered User</H4><!--SEC END -->
|
|
|
|
<BLOCKQUOTE><DIV ALIGN=center><DIV ALIGN=center><HR WIDTH="80%" SIZE=2></DIV>
|
|
|
|
<IMG SRC="discoallusers.png">
|
|
|
|
|
|
<BR>
|
|
<DIV ALIGN=center>Figure 4: Discovery all users</DIV><BR>
|
|
|
|
<A NAME="fig:discoallusers"></A>
|
|
<DIV ALIGN=center><HR WIDTH="80%" SIZE=2></DIV></DIV></BLOCKQUOTE>
|
|
<!--TOC subsubsection Node <TT>outgoing s2s</TT>: List of Outgoing S2S connections-->
|
|
|
|
<H4><A NAME="htoc22">3.2.4</A> Node <TT>outgoing s2s</TT>: List of Outgoing S2S connections</H4><!--SEC END -->
|
|
|
|
<!--TOC subsubsection Node <TT>running nodes</TT>: List of Running <TT>ejabberd</TT> Nodes-->
|
|
|
|
<H4><A NAME="htoc23">3.2.5</A> Node <TT>running nodes</TT>: List of Running <TT>ejabberd</TT> Nodes</H4><!--SEC END -->
|
|
|
|
<BLOCKQUOTE><DIV ALIGN=center><DIV ALIGN=center><HR WIDTH="80%" SIZE=2></DIV>
|
|
|
|
<IMG SRC="discorunnodes.png">
|
|
|
|
|
|
<BR>
|
|
<DIV ALIGN=center>Figure 5: Discovery running nodes</DIV><BR>
|
|
|
|
<A NAME="fig:discorunnodes"></A>
|
|
<DIV ALIGN=center><HR WIDTH="80%" SIZE=2></DIV></DIV></BLOCKQUOTE>
|
|
<!--TOC subsubsection Node <TT>stopped nodes</TT>: List of Stopped Nodes-->
|
|
|
|
<H4><A NAME="htoc24">3.2.6</A> Node <TT>stopped nodes</TT>: List of Stopped Nodes</H4><!--SEC END -->
|
|
|
|
TBD<BR>
|
|
<BR>
|
|
<!--TOC section Distribution-->
|
|
|
|
<H2><A NAME="htoc25">4</A> Distribution</H2><!--SEC END -->
|
|
|
|
<A NAME="sec:distribution"></A>
|
|
<!--TOC subsection How it works-->
|
|
|
|
<H3><A NAME="htoc26">4.1</A> How it works</H3><!--SEC END -->
|
|
|
|
<A NAME="sec:howitworks"></A>
|
|
A Jabber domain is served by one or more <TT>ejabberd</TT> nodes. These nodes can
|
|
be run on different machines that are connected via a network. They all must
|
|
have the ability to connect to port 4369 of all another nodes, and must have
|
|
the same magic cookie (see Erlang/OTP documentation, in other words the file
|
|
<TT>~ejabberd/.erlang.cookie</TT> must be the same on all nodes). This is
|
|
needed because all nodes exchange information about connected users, S2S
|
|
connections, registered services, etc...<BR>
|
|
<BR>
|
|
Each <TT>ejabberd</TT> node have following modules:
|
|
<UL><LI>
|
|
router;
|
|
<LI>local router.
|
|
<LI>session manager;
|
|
<LI>S2S manager;
|
|
</UL>
|
|
<!--TOC subsubsection Router-->
|
|
|
|
<H4><A NAME="htoc27">4.1.1</A> Router</H4><!--SEC END -->
|
|
|
|
This module is the main router of Jabber packets on each node. It routes
|
|
them based on their destinations domains. It has two tables: local and global
|
|
routes. First, domain of packet destination searched in local table, and if it
|
|
found, then the packet is routed to appropriate process. If no, then it
|
|
searches in global table, and is routed to the appropriate <TT>ejabberd</TT> node or
|
|
process. If it does not exists in either tables, then it sent to the S2S
|
|
manager.<BR>
|
|
<BR>
|
|
<!--TOC subsubsection Local Router-->
|
|
|
|
<H4><A NAME="htoc28">4.1.2</A> Local Router</H4><!--SEC END -->
|
|
|
|
This module routes packets which have a destination domain equal to this server
|
|
name. If destination JID has a non-empty user part, then it routed to the
|
|
session manager, else it is processed depending on it's content.<BR>
|
|
<BR>
|
|
<!--TOC subsubsection Session Manager-->
|
|
|
|
<H4><A NAME="htoc29">4.1.3</A> Session Manager</H4><!--SEC END -->
|
|
|
|
This module routes packets to local users. It searches for what user resource
|
|
packet must be sended via presence table. If this resource is connected to
|
|
this node, it is routed to C2S process, if it connected via another node, then
|
|
the packet is sent to session manager on that node.<BR>
|
|
<BR>
|
|
<!--TOC subsubsection S2S Manager-->
|
|
|
|
<H4><A NAME="htoc30">4.1.4</A> S2S Manager</H4><!--SEC END -->
|
|
|
|
This module routes packets to other Jabber servers. First, it checks if an
|
|
open S2S connection from the domain of the packet source to the domain of
|
|
packet destination already exists. If it is open on another node, then it
|
|
routes the packet to S2S manager on that node, if it is open on this node, then
|
|
it is routed to the process that serves this connection, and if a connection
|
|
does not exist, then it is opened and registered.<BR>
|
|
<BR>
|
|
<!--TOC section Built-in Modules-->
|
|
|
|
<H2><A NAME="htoc31">A</A> Built-in Modules</H2><!--SEC END -->
|
|
|
|
<A NAME="sec:modules"></A>
|
|
<!--TOC subsection Common Options-->
|
|
|
|
<H3><A NAME="htoc32">A.1</A> Common Options</H3><!--SEC END -->
|
|
|
|
<A NAME="sec:modcommonopts"></A>
|
|
Following options used by many modules, so they described in separate section.<BR>
|
|
<BR>
|
|
<!--TOC subsubsection Option <TT>iqdisc</TT>-->
|
|
|
|
<H4><A NAME="htoc33">A.1.1</A> Option <TT>iqdisc</TT></H4><!--SEC END -->
|
|
|
|
Many modules define handlers for processing IQ queries of different namespaces
|
|
to this server or to user (e. g. to <TT>myjabber.org</TT> or to
|
|
<TT>user@myjabber.org</TT>). This option defines processing discipline of
|
|
these queries. Possible values are:
|
|
<DL COMPACT=compact><DT>
|
|
<B><TT>no_queue</TT></B><DD> All queries of namespace with this processing
|
|
discipline processed immediately. This also means that no other packets can
|
|
be processed until finished this. Hence this discipline is not recommended
|
|
if processing of query can take relative many time.
|
|
<DT><B><TT>one_queue</TT></B><DD> In this case created separate queue for processing
|
|
IQ queries of namespace with this discipline, and processing of this queue
|
|
done in parallel with processing of other packets. This discipline is most
|
|
recommended.
|
|
<DT><B><TT>parallel</TT></B><DD> In this case for all packets with this discipline
|
|
spawned separate Erlang process, so all these packets processed in parallel.
|
|
Although spawning of Erlang process have relative low cost, this can broke
|
|
server normal work, because Erlang have limit of 32000 processes.
|
|
</DL>
|
|
Example:
|
|
<PRE>
|
|
{modules, [
|
|
...
|
|
{mod_time, [{iqdisc, no_queue}]},
|
|
...
|
|
]}.
|
|
</PRE>
|
|
<!--TOC subsubsection Option <TT>host</TT>-->
|
|
|
|
<H4><A NAME="htoc34">A.1.2</A> Option <TT>host</TT></H4><!--SEC END -->
|
|
|
|
Some modules may act as services, and wants to have different domain name.
|
|
This option explicitly defines this name.<BR>
|
|
<BR>
|
|
Example:
|
|
<PRE>
|
|
{modules, [
|
|
...
|
|
{mod_echo, [{host, "echo.myjabber.org"}]},
|
|
...
|
|
]}.
|
|
</PRE>
|
|
<!--TOC subsection <TT>mod_register</TT>-->
|
|
|
|
<H3><A NAME="htoc35">A.2</A> <TT>mod_register</TT></H3><!--SEC END -->
|
|
|
|
<A NAME="sec:modregister"></A>
|
|
<!--TOC subsection <TT>mod_roster</TT>-->
|
|
|
|
<H3><A NAME="htoc36">A.3</A> <TT>mod_roster</TT></H3><!--SEC END -->
|
|
|
|
<A NAME="sec:modroster"></A>
|
|
<!--TOC subsection <TT>mod_configure</TT>-->
|
|
|
|
<H3><A NAME="htoc37">A.4</A> <TT>mod_configure</TT></H3><!--SEC END -->
|
|
|
|
<A NAME="sec:modconfigure"></A>
|
|
<!--TOC subsection <TT>mod_disco</TT>-->
|
|
|
|
<H3><A NAME="htoc38">A.5</A> <TT>mod_disco</TT></H3><!--SEC END -->
|
|
|
|
<A NAME="sec:moddisco"></A>
|
|
<!--TOC subsection <TT>mod_stats</TT>-->
|
|
|
|
<H3><A NAME="htoc39">A.6</A> <TT>mod_stats</TT></H3><!--SEC END -->
|
|
|
|
<A NAME="sec:modstats"></A>
|
|
This module adds support of
|
|
<A HREF="http://www.jabber.org/jeps/jep-0039.html">JEP-0039</A> (Statistics Gathering).<BR>
|
|
<BR>
|
|
Options:
|
|
<DL COMPACT=compact><DT>
|
|
<B><TT>iqdisc</TT></B><DD> <TT>http://jabber.org/protocol/stats</TT> IQ queries
|
|
processing discipline.
|
|
</DL>
|
|
TBD about access.<BR>
|
|
<BR>
|
|
<!--TOC subsection <TT>mod_vcard</TT>-->
|
|
|
|
<H3><A NAME="htoc40">A.7</A> <TT>mod_vcard</TT></H3><!--SEC END -->
|
|
|
|
<A NAME="sec:modvcard"></A>
|
|
<!--TOC subsection <TT>mod_offline</TT>-->
|
|
|
|
<H3><A NAME="htoc41">A.8</A> <TT>mod_offline</TT></H3><!--SEC END -->
|
|
|
|
<A NAME="sec:modoffline"></A>
|
|
<!--TOC subsection <TT>mod_echo</TT>-->
|
|
|
|
<H3><A NAME="htoc42">A.9</A> <TT>mod_echo</TT></H3><!--SEC END -->
|
|
|
|
<A NAME="sec:modecho"></A>
|
|
<!--TOC subsection <TT>mod_private</TT>-->
|
|
|
|
<H3><A NAME="htoc43">A.10</A> <TT>mod_private</TT></H3><!--SEC END -->
|
|
|
|
<A NAME="sec:modprivate"></A>
|
|
This module adds support of
|
|
<A HREF="http://www.jabber.org/jeps/jep-0049.html">JEP-0049</A> (Private XML
|
|
Storage).<BR>
|
|
<BR>
|
|
Options:
|
|
<DL COMPACT=compact><DT>
|
|
<B><TT>iqdisc</TT></B><DD> <TT>jabber:iq:private</TT> IQ queries processing discipline.
|
|
</DL>
|
|
<!--TOC subsection <TT>mod_time</TT>-->
|
|
|
|
<H3><A NAME="htoc44">A.11</A> <TT>mod_time</TT></H3><!--SEC END -->
|
|
|
|
<A NAME="sec:modtime"></A>
|
|
This module answers UTC time on <TT>jabber:iq:time</TT> queries.<BR>
|
|
<BR>
|
|
Options:
|
|
<DL COMPACT=compact><DT>
|
|
<B><TT>iqdisc</TT></B><DD> <TT>jabber:iq:time</TT> IQ queries processing discipline.
|
|
</DL>
|
|
<!--TOC subsection <TT>mod_version</TT>-->
|
|
|
|
<H3><A NAME="htoc45">A.12</A> <TT>mod_version</TT></H3><!--SEC END -->
|
|
|
|
<A NAME="sec:modversion"></A>
|
|
This module answers <TT>ejabberd</TT> version on <TT>jabber:iq:version</TT> queries.<BR>
|
|
<BR>
|
|
Options:
|
|
<DL COMPACT=compact><DT>
|
|
<B><TT>iqdisc</TT></B><DD> <TT>jabber:iq:version</TT> IQ queries processing discipline.
|
|
</DL>
|
|
<!--TOC section I18n/L10n-->
|
|
|
|
<H2><A NAME="htoc46">B</A> I18n/L10n</H2><!--SEC END -->
|
|
|
|
<A NAME="sec:i18nl10n"></A>
|
|
Many modules supports <TT>xml:lang</TT> attribute inside IQ queries. E. g.
|
|
on figure <A HREF="#fig:discorus">6</A> (compare with figure <A HREF="#fig:disco">1</A>) showed reply
|
|
on following query:
|
|
<PRE>
|
|
<iq id='5'
|
|
to='e.localhost'
|
|
type='get'>
|
|
<query xmlns='http://jabber.org/protocol/disco#items'
|
|
xml:lang='ru'/>
|
|
</iq>
|
|
</PRE>
|
|
<BLOCKQUOTE><DIV ALIGN=center><DIV ALIGN=center><HR WIDTH="80%" SIZE=2></DIV>
|
|
|
|
<IMG SRC="discorus.png">
|
|
|
|
|
|
<BR>
|
|
<DIV ALIGN=center>Figure 6: Discovery result when <TT>xml:lang='ru'</TT></DIV><BR>
|
|
|
|
<A NAME="fig:discorus"></A>
|
|
<DIV ALIGN=center><HR WIDTH="80%" SIZE=2></DIV></DIV></BLOCKQUOTE>
|
|
<!--HTMLFOOT-->
|
|
<!--ENDHTML-->
|
|
<!--FOOTER-->
|
|
<HR SIZE=2>
|
|
<BLOCKQUOTE><EM>This document was translated from L<sup>A</sup>T<sub>E</sub>X by
|
|
</EM><A HREF="http://pauillac.inria.fr/~maranget/hevea/index.html"><EM>H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A</EM></A><EM>.
|
|
</EM></BLOCKQUOTE>
|
|
</BODY>
|
|
</HTML>
|