Chapril/xmpp.chapril.org-ejabberd
25
1
Fork 0
mirror of https://github.com/processone/ejabberd.git synced 2024-11-04 15:36:57 +01:00
Code Releases Activity
6b1e56f786
xmpp.chapril.org-ejabberd/doc/guide.html
Alexey Shchepin e93f2aa1e1 * doc/guide.tex: Added mod_shared_roster documentation 
* src/ejabberd.hrl: Updated version

SVN Revision: 326
2005-04-22 16:47:16 +00:00

1467 lines
55 KiB
HTML
Raw Blame History

<!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=ISO8859-1">
<META name="GENERATOR" content="hevea 1.07">
</HEAD>
<BODY >
<!--HEVEA command line is: /usr/bin/hevea -charset ISO8859-1 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>April 18, 2005</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&nbsp;&nbsp;Introduction</A>
<LI><A HREF="#htoc2">2&nbsp;&nbsp;Installation from Source</A>
<UL><LI>
<A HREF="#htoc3">2.1&nbsp;&nbsp;Installation Requirements</A>
<UL><LI>
<A HREF="#htoc4">2.1.1&nbsp;&nbsp;Unix</A>
<LI><A HREF="#htoc5">2.1.2&nbsp;&nbsp;Windows</A>
</UL>
<LI><A HREF="#htoc6">2.2&nbsp;&nbsp;Obtaining</A>
<LI><A HREF="#htoc7">2.3&nbsp;&nbsp;Compilation</A>
<UL><LI>
<A HREF="#htoc8">2.3.1&nbsp;&nbsp;Unix</A>
<LI><A HREF="#htoc9">2.3.2&nbsp;&nbsp;Windows</A>
</UL>
<LI><A HREF="#htoc10">2.4&nbsp;&nbsp;Starting</A>
</UL>
<LI><A HREF="#htoc11">3&nbsp;&nbsp;Configuration</A>
<UL><LI>
<A HREF="#htoc12">3.1&nbsp;&nbsp;Initial Configuration</A>
<UL><LI>
<A HREF="#htoc13">3.1.1&nbsp;&nbsp;Host Names</A>
<LI><A HREF="#htoc14">3.1.2&nbsp;&nbsp;Default Language</A>
<LI><A HREF="#htoc15">3.1.3&nbsp;&nbsp;Access Rules</A>
<LI><A HREF="#htoc16">3.1.4&nbsp;&nbsp;Shapers Configuration</A>
<LI><A HREF="#htoc17">3.1.5&nbsp;&nbsp;Listened Sockets</A>
<LI><A HREF="#htoc18">3.1.6&nbsp;&nbsp;Modules</A>
</UL>
<LI><A HREF="#htoc19">3.2&nbsp;&nbsp;Online Configuration and Monitoring</A>
<UL><LI>
<A HREF="#htoc20">3.2.1&nbsp;&nbsp;Web-based Administration Interface</A>
<LI><A HREF="#htoc21">3.2.2&nbsp;&nbsp;<TT>ejabberdctl</TT> tool</A>
</UL>
</UL>
<LI><A HREF="#htoc22">4&nbsp;&nbsp;Clustering</A>
<UL><LI>
<A HREF="#htoc23">4.1&nbsp;&nbsp;How it works</A>
<UL><LI>
<A HREF="#htoc24">4.1.1&nbsp;&nbsp;Router</A>
<LI><A HREF="#htoc25">4.1.2&nbsp;&nbsp;Local Router</A>
<LI><A HREF="#htoc26">4.1.3&nbsp;&nbsp;Session Manager</A>
<LI><A HREF="#htoc27">4.1.4&nbsp;&nbsp;S2S Manager</A>
</UL>
<LI><A HREF="#htoc28">4.2&nbsp;&nbsp;How to setup ejabberd cluster</A>
</UL>
<LI><A HREF="#htoc29">A&nbsp;&nbsp;Built-in Modules</A>
<UL><LI>
<A HREF="#htoc30">A.1&nbsp;&nbsp;Common Options</A>
<UL><LI>
<A HREF="#htoc31">A.1.1&nbsp;&nbsp;<TT>iqdisc</TT></A>
<LI><A HREF="#htoc32">A.1.2&nbsp;&nbsp;<TT>host</TT></A>
<LI><A HREF="#htoc33">A.1.3&nbsp;&nbsp;<TT>hosts</TT></A>
</UL>
<LI><A HREF="#htoc34">A.2&nbsp;&nbsp;<TT>mod_announce</TT></A>
<LI><A HREF="#htoc35">A.3&nbsp;&nbsp;<TT>mod_configure</TT></A>
<LI><A HREF="#htoc36">A.4&nbsp;&nbsp;<TT>mod_disco</TT></A>
<LI><A HREF="#htoc37">A.5&nbsp;&nbsp;<TT>mod_echo</TT></A>
<LI><A HREF="#htoc38">A.6&nbsp;&nbsp;<TT>mod_irc</TT></A>
<LI><A HREF="#htoc39">A.7&nbsp;&nbsp;<TT>mod_last</TT></A>
<LI><A HREF="#htoc40">A.8&nbsp;&nbsp;<TT>mod_muc</TT></A>
<LI><A HREF="#htoc41">A.9&nbsp;&nbsp;<TT>mod_offline</TT></A>
<LI><A HREF="#htoc42">A.10&nbsp;&nbsp;<TT>mod_privacy</TT></A>
<LI><A HREF="#htoc43">A.11&nbsp;&nbsp;<TT>mod_private</TT></A>
<LI><A HREF="#htoc44">A.12&nbsp;&nbsp;<TT>mod_pubsub</TT></A>
<LI><A HREF="#htoc45">A.13&nbsp;&nbsp;<TT>mod_register</TT></A>
<LI><A HREF="#htoc46">A.14&nbsp;&nbsp;<TT>mod_roster</TT></A>
<LI><A HREF="#htoc47">A.15&nbsp;&nbsp;<TT>mod_service_log</TT></A>
<LI><A HREF="#htoc48">A.16&nbsp;&nbsp;<TT>mod_shared_roster</TT></A>
<LI><A HREF="#htoc49">A.17&nbsp;&nbsp;<TT>mod_stats</TT></A>
<LI><A HREF="#htoc50">A.18&nbsp;&nbsp;<TT>mod_time</TT></A>
<LI><A HREF="#htoc51">A.19&nbsp;&nbsp;<TT>mod_vcard</TT></A>
<LI><A HREF="#htoc52">A.20&nbsp;&nbsp;<TT>mod_version</TT></A>
</UL>
<LI><A HREF="#htoc53">B&nbsp;&nbsp;I18n/L10n</A>
</UL>
<!--TOC section Introduction-->
<H2><A NAME="htoc1">1</A>&nbsp;&nbsp;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 written mostly in Erlang.<BR>
<BR>
The main features of <TT>ejabberd</TT> are:
<UL><LI>
Works on most of popular platforms: *nix (tested on Linux, FreeBSD and
NetBSD) and Win32
<LI>Distributed: You can run <TT>ejabberd</TT> on a cluster of machines to let all of
them serve one Jabber domain.
<LI>Fault-tolerance: You can 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 nodes ``on the fly''.
<LI>Support for virtual hosting
<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>Built-in web-based administration interface
<LI>Built-in <A HREF="http://www.jabber.org/jeps/jep-0025.html">HTTP Polling</A> service
<LI>SSL support
<LI>Support for LDAP authentication
<LI>Ability to interface with external components (JIT, MSN-t, Yahoo-t, etc.)
<LI>Migration from jabberd14 is possible
<LI>Mostly XMPP-compliant
<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>
</UL>
The misfeatures of <TT>ejabberd</TT> are:
<UL><LI>
No support for authentication and STARTTLS in S2S connections
<LI>Access rules can be defined only for global conext, not for specific
virtual host
</UL>
<!--TOC section Installation from Source-->
<H2><A NAME="htoc2">2</A>&nbsp;&nbsp;Installation from Source</H2><!--SEC END -->
<A NAME="sec:installation"></A>
<!--TOC subsection Installation Requirements-->
<H3><A NAME="htoc3">2.1</A>&nbsp;&nbsp;Installation Requirements</H3><!--SEC END -->
<A NAME="sec:installreq"></A>
<!--TOC subsubsection Unix-->
<H4><A NAME="htoc4">2.1.1</A>&nbsp;&nbsp;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;
<LI>OpenSSL 0.9.6 or later (optional).
</UL>
<!--TOC subsubsection Windows-->
<H4><A NAME="htoc5">2.1.2</A>&nbsp;&nbsp;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://erlang.org/download/otp_win32_R10B-1a.exe">Erlang/OTP R10B-1a</A>
<LI><A HREF="http://prdownloads.sourceforge.net/expat/expat_win32bin_1_95_7.exe?download">Expat 1.95.7</A>
<LI><A HREF="http://ftp.gnu.org/pub/gnu/libiconv/libiconv-1.9.1.tar.gz">Iconv 1.9.1</A>
(optional)
<LI><A HREF="http://www.slproweb.com/products/Win32OpenSSL.html">Shining Light OpenSSL</A>
(to enable SSL connections)
</UL>
<!--TOC subsection Obtaining-->
<H3><A NAME="htoc6">2.2</A>&nbsp;&nbsp;Obtaining</H3><!--SEC END -->
<A NAME="sec:obtaining"></A>
Stable <TT>ejabberd</TT> release can be obtained at
<A HREF="http://www.process-one.net/en/projects/ejabberd/download.html"><TT>http://www.process-one.net/en/projects/ejabberd/download.html</TT></A>.<BR>
<BR>
The latest alpha version can be retrieved from Subversion repository.
<PRE>
svn co svn://svn.process-one.net/opt/data/svn/ejabberd/trunk ejabberd
</PRE>
<!--TOC subsection Compilation-->
<H3><A NAME="htoc7">2.3</A>&nbsp;&nbsp;Compilation</H3><!--SEC END -->
<A NAME="sec:compilation"></A>
<!--TOC subsubsection Unix-->
<H4><A NAME="htoc8">2.3.1</A>&nbsp;&nbsp;Unix</H4><!--SEC END -->
<A NAME="sec:compilationunix"></A>
<PRE>
./configure
make
su
make install
</PRE>
This will install <TT>ejabberd</TT> to <CODE>/var/lib/ejabberd</CODE> directory,
<CODE>ejabberd.cfg</CODE> to <CODE>/etc/ejabberd</CODE> directory and create
<CODE>/var/log/ejabberd</CODE> directory for log files.<BR>
<BR>
<!--TOC subsubsection Windows-->
<H4><A NAME="htoc9">2.3.2</A>&nbsp;&nbsp;Windows</H4><!--SEC END -->
<A NAME="sec:compilationwin"></A>
<UL><LI>
Install Erlang emulator (for example, into <CODE>C:\Program Files\erl5.3</CODE>).
<LI>Install Expat library into <CODE>C:\Program Files\Expat-1.95.7</CODE>
directory.<BR>
<BR>
Copy file <CODE>C:\Program Files\Expat-1.95.7\Libs\libexpat.dll</CODE>
to your Windows system directory (for example, <CODE>C:\WINNT</CODE> or
<CODE>C:\WINNT\System32</CODE>)
<LI>Build and install Iconv library into <CODE>C:\Program Files\iconv-1.9.1</CODE> directory.<BR>
<BR>
Copy file <CODE>C:\Program Files\iconv-1.9.1\bin\iconv.dll</CODE> to your
Windows system directory.<BR>
<BR>
Note: Instead of copying libexpat.dll and iconv.dll to Windows
directory, you can add directories
<CODE>C:\Program Files\Expat-1.95.7\Libs</CODE> and
<CODE>C:\Program Files\iconv-1.9.1\bin</CODE> to <CODE>PATH</CODE> environment
variable.
<LI>Being in <CODE>ejabberd\src</CODE> directory run:
<PRE>
configure.bat
nmake -f Makefile.win32
</PRE><LI>Edit file <CODE>ejabberd\src\ejabberd.cfg</CODE> and run
<PRE>
werl -s ejabberd -name ejabberd
</PRE></UL>
<!--TOC subsection Starting-->
<H3><A NAME="htoc10">2.4</A>&nbsp;&nbsp;Starting</H3><!--SEC END -->
<A NAME="sec:starting"></A>
To start <TT>ejabberd</TT>, use the following command:
<PRE>
erl -pa /var/lib/ejabberd/ebin -name ejabberd -s ejabberd
</PRE>or
<PRE>
erl -pa /var/lib/ejabberd/ebin -sname ejabberd -s ejabberd
</PRE>In the latter case Erlang node will be identified using only first part of host
name, i.&nbsp;e. other Erlang nodes outside this domain can't contact this node.<BR>
<BR>
Note that when using above command <TT>ejabberd</TT> will search for config file
in current directory and will use current directory for storing user database
and logging.<BR>
<BR>
To specify path to config file, log files and Mnesia database directory,
you may use the following command:
<PRE>
erl -pa /var/lib/ejabberd/ebin \
-sname ejabberd \
-s ejabberd \
-ejabberd config \"/etc/ejabberd/ejabberd.cfg\" \
log_path \"/var/log/ejabberd/ejabberd.log\" \
-sasl sasl_error_logger \{file,\"/var/log/ejabberd/sasl.log\"\} \
-mnesia dir \"/var/lib/ejabberd/spool\"
</PRE>
You can find other useful options in Erlang manual page (<TT>erl -man erl</TT>).<BR>
<BR>
To use more than 1024 connections, you should set environment variable
<CODE>ERL_MAX_PORTS</CODE>:
<PRE>
export ERL_MAX_PORTS=32000
</PRE>Note that with this value <TT>ejabberd</TT> will use more memory (approximately 6MB
more).<BR>
<BR>
To reduce memory usage, you may set environment variable
<CODE>ERL_FULLSWEEP_AFTER</CODE>:
<PRE>
export ERL_FULLSWEEP_AFTER=0
</PRE>But in this case <TT>ejabberd</TT> can start to work slower.<BR>
<BR>
<!--TOC section Configuration-->
<H2><A NAME="htoc11">3</A>&nbsp;&nbsp;Configuration</H2><!--SEC END -->
<A NAME="sec:configuration"></A>
<!--TOC subsection Initial Configuration-->
<H3><A NAME="htoc12">3.1</A>&nbsp;&nbsp;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. Subsequently 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.&nbsp;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 Names-->
<H4><A NAME="htoc13">3.1.1</A>&nbsp;&nbsp;Host Names</H4><!--SEC END -->
<A NAME="sec:confighostname"></A>
Option <TT>hosts</TT> defines a list of Jabber domains that <TT>ejabberd</TT>
serves. E.&nbsp;g. to serve <TT>example.org</TT> and <TT>example.com</TT> domains add
the following line in the config:
<PRE>
{hosts, ["example.org", "example.com"]}.
</PRE>
Option <TT>host</TT> defines one Jabber domain that <TT>ejabberd</TT> serves.
E.&nbsp;g. to serve only <TT>example.org</TT> domain add the following line in the
config:
<PRE>
{host, "example.org"}.
</PRE>It have the same effect as
<PRE>
{hosts, ["example.org"]}.
</PRE>
<!--TOC subsubsection Default Language-->
<H4><A NAME="htoc14">3.1.2</A>&nbsp;&nbsp;Default Language</H4><!--SEC END -->
<A NAME="sec:configlanguage"></A>
Option <TT>language</TT> defines default language of <TT>ejabberd</TT> messages, sent
to users. Default value is <TT>"en"</TT>. In order to take effect there must be a
translation file <TT>&lt;language&gt;.msg</TT> in <TT>ejabberd</TT> <TT>msgs</TT> directory.
E.&nbsp;g. to use Russian as default language add the following line in the config:
<PRE>
{language, "ru"}.
</PRE>
<!--TOC subsubsection Access Rules-->
<H4><A NAME="htoc15">3.1.3</A>&nbsp;&nbsp;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, &lt;aclname&gt;, {&lt;acltype&gt;, ...}}.
</PRE>
<TT>&lt;acltype&gt;</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, &lt;username&gt;}</TT></B><DD> Matches user with name
<TT>&lt;username&gt;</TT> at the first virtual host. Example:
<PRE>
{acl, admin, {user, "aleksey"}}.
</PRE><DT><B><TT>{user, &lt;username&gt;, &lt;server&gt;}</TT></B><DD> Matches user with JID
<TT>&lt;username&gt;@&lt;server&gt;</TT> and any resource. Example:
<PRE>
{acl, admin, {user, "aleksey", "jabber.ru"}}.
</PRE><DT><B><TT>{server, &lt;server&gt;}</TT></B><DD> Matches any JID from server
<TT>&lt;server&gt;</TT>. Example:
<PRE>
{acl, jabberorg, {server, "jabber.org"}}.
</PRE><DT><B><TT>{user_regexp, &lt;regexp&gt;}</TT></B><DD> Matches local user with name that
matches <TT>&lt;regexp&gt;</TT> at the first virtual host. Example:
<PRE>
{acl, tests, {user, "^test[0-9]*$"}}.
</PRE><DT><B><TT>{user_regexp, &lt;regexp&gt;, &lt;server&gt;}</TT></B><DD> Matches user with name
that matches <TT>&lt;regexp&gt;</TT> and from server <TT>&lt;server&gt;</TT>. Example:
<PRE>
{acl, tests, {user, "^test", "localhost"}}.
</PRE><DT><B><TT>{server_regexp, &lt;regexp&gt;}</TT></B><DD> Matches any JID from server that
matches <TT>&lt;regexp&gt;</TT>. Example:
<PRE>
{acl, icq, {server, "^icq\\."}}.
</PRE><DT><B><TT>{node_regexp, &lt;user_regexp&gt;, &lt;server_regexp&gt;}</TT></B><DD> Matches user
with name that matches <TT>&lt;user_regexp&gt;</TT> and from server that matches
<TT>&lt;server_regexp&gt;</TT>. Example:
<PRE>
{acl, aleksey, {node_regexp, "^aleksey$", "^jabber.(ru|org)$"}}.
</PRE><DT><B><TT>{user_glob, &lt;glob&gt;}</TT></B><DD>
<DT><B><TT>{user_glob, &lt;glob&gt;, &lt;server&gt;}</TT></B><DD>
<DT><B><TT>{server_glob, &lt;glob&gt;}</TT></B><DD>
<DT><B><TT>{node_glob, &lt;user_glob&gt;, &lt;server_glob&gt;}</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 are 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 access to different services would look similar to
this:
<PRE>
{access, &lt;accessname&gt;, [{allow, &lt;aclname&gt;},
{deny, &lt;aclname&gt;},
...
]}.
</PRE>When a JID is checked to have access to <TT>&lt;accessname&gt;</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 returns ``<TT>allow</TT>''
<DT><B><TT>none</TT></B><DD> Always returns ``<TT>deny</TT>''
</DL>
<!--TOC subsubsection Shapers Configuration-->
<H4><A NAME="htoc16">3.1.4</A>&nbsp;&nbsp;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, &lt;shapername&gt;, &lt;kind&gt;}.
</PRE>Currently implemented only one kind of shaper: <TT>maxrate</TT>. It have
following syntax:
<PRE>
{maxrate, &lt;rate&gt;}
</PRE>where <TT>&lt;rate&gt;</TT> means maximum allowed incomig rate in bytes/second.
E.&nbsp;g. to define shaper with name ``<TT>normal</TT>'' and maximum allowed rate
1000&nbsp;bytes/s, add following line in config:
<PRE>
{shaper, normal, {maxrate, 1000}}.
</PRE>
<!--TOC subsubsection Listened Sockets-->
<H4><A NAME="htoc17">3.1.5</A>&nbsp;&nbsp;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>Options to this module.
</UL>
Currently these modules are implemented:
<DL COMPACT=compact><DT>
<B><TT>ejabberd_c2s</TT></B><DD> This module serves C2S connections.<BR>
<BR>
The following options are defined:
<DL COMPACT=compact><DT>
<B><TT>{access, &lt;access rule&gt;}</TT></B><DD> This option defines access of users
to this C2S port. Default value is ``<TT>all</TT>''.
<DT><B><TT>{shaper, &lt;access rule&gt;}</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>''.
<DT><B><TT>{ip, IPAddress}</TT></B><DD> This option specifies which network interface to
listen on. For example <CODE>{ip, {192, 168, 1, 1}}</CODE>.
<DT><B><TT>inet6</TT></B><DD> Set up the socket for IPv6.
<DT><B><TT>starttls</TT></B><DD> This option specifies that STARTTLS extension is available
on connections to this port. You should also set ``<CODE>certfile</CODE>''
option.
<DT><B><TT>tls</TT></B><DD> This option specifies that traffic on this port will be
encrypted using SSL immediately after connecting. You should also set
``<CODE>certfile</CODE>'' option.
<DT><B><TT>ssl</TT></B><DD> This option specifies that traffic on this port will be
encrypted using SSL. You should also set ``<CODE>certfile</CODE>'' option. It
is recommended to use <TT>tls</TT> option instead.
<DT><B><TT>{certfile, Path}</TT></B><DD> Path to a file containing the SSL certificate.
</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.&nbsp;e. that use the <TT>jabber:component:accept</TT> namespace).<BR>
<BR>
The following additional options are defined for <TT>ejabberd_service</TT>
(options <TT>access</TT>, <TT>shaper</TT>, <TT>ip</TT>, <TT>inet6</TT> are
still valid):
<DL COMPACT=compact><DT>
<B><TT>{host, Hostname, [HostOptions]}</TT></B><DD> This option defines hostname of connected
service and allows to specify additional options, e.&nbsp;g.
<TT>{password, Secret}</TT>.
<DT><B><TT>{hosts, [Hostnames], [HostOptions]}</TT></B><DD> The same as above, but allows to
specify several hostnames.
</DL>
<DT><B><TT>ejabberd_http</TT></B><DD> This module serves incoming HTTP connections.<BR>
<BR>
The following options are defined:
<DL COMPACT=compact><DT>
<B><TT>http_poll</TT></B><DD> This option enables <A HREF="http://www.jabber.org/jeps/jep-0025.html">HTTP Polling</A>
support. It is available then at <CODE>http://server:port/http-poll/</CODE>.<BR>
<BR>
<DT><B><TT>web_admin</TT></B><DD> This option enables web-based interface for <TT>ejabberd</TT>
administration which is available at <CODE>http://server:port/admin/</CODE>,
login and password should be equal to username and password of one of
registered users who have permission defined in ``configure'' access rule.
</DL>
</DL>
For example, the following configuration defines that:
<UL><LI>
C2S connections are listened on port 5222 and 5223 (SSL) and denied for
user ``<TT>bad</TT>''
<LI>S2S connections are listened on port 5269
<LI>HTTP connections are listened on port 5280 and administration interface
and HTTP Polling support are enabled
<LI>All users except admins have traffic limit 1000&nbsp;B/s
<LI>AIM transport <TT>aim.example.org</TT> is connected to port 5233 with
password ``<TT>aimsecret</TT>''
<LI>JIT transports <TT>icq.example.org</TT> and <TT>sms.example.org</TT> are
connected to port 5234 with password ``<TT>jitsecret</TT>''
<LI>MSN transport <TT>msn.example.org</TT> is connected to port 5235 with
password ``<TT>msnsecret</TT>''
<LI>Yahoo! transport <TT>yahoo.example.org</TT> is connected to port 5236 with
password ``<TT>yahoosecret</TT>''
<LI>Gadu-Gadu transport <TT>gg.example.org</TT> is connected to port 5237 with
password ``<TT>ggsecret</TT>''
<LI>ILE service <TT>ile.example.org</TT> is connected to port 5238 with
password ``<TT>ilesecret</TT>''
</UL>
<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, [{access, c2s}, {shaper, c2s_shaper}]},
{5223, ejabberd_c2s, [{access, c2s},
ssl, {certfile, "/path/to/ssl.pem"}]},
{5269, ejabberd_s2s_in, []},
{5280, ejabberd_http, [http_poll, web_admin]},
{5233, ejabberd_service, [{host, "aim.example.org",
[{password, "aimsecret"}]}]},
{5234, ejabberd_service, [{hosts, ["icq.example.org", "sms.example.org"],
[{password, "jitsecret"}]}]},
{5235, ejabberd_service, [{host, "msn.example.org",
[{password, "msnsecret"}]}]},
{5236, ejabberd_service, [{host, "yahoo.example.org",
[{password, "yahoosecret"}]}]},
{5237, ejabberd_service, [{host, "gg.example.org",
[{password, "ggsecret"}]}]},
{5238, ejabberd_service, [{host, "ile.example.org",
[{password, "ilesecret"}]}]}
]
}.
</PRE>Note, that for jabberd14- or wpjabberd-based services you have to make the
transports log and do XDB by themselves:
<PRE>
&lt;!--
You have to add elogger and rlogger entries here when using ejabberd.
In this case the transport will do the logging.
--&gt;
&lt;log id='logger'&gt;
&lt;host/&gt;
&lt;logtype/&gt;
&lt;format&gt;%d: [%t] (%h): %s&lt;/format&gt;
&lt;file&gt;/var/log/jabber/service.log&lt;/file&gt;
&lt;/log&gt;
&lt;!--
Some Jabber server implementations do not provide
XDB services (for example jabberd 2.0 and ejabberd).
xdb_file_so is loaded in to handle all XDB requests.
--&gt;
&lt;xdb id="xdb"&gt;
&lt;host/&gt;
&lt;load&gt;
&lt;!-- this is a lib of wpjabber or jabberd --&gt;
&lt;xdb_file&gt;/usr/lib/jabber/xdb_file.so&lt;/xdb_file&gt;
&lt;/load&gt;
&lt;xdb_file xmlns="jabber:config:xdb_file"&gt;
&lt;spool&gt;&lt;jabberd:cmdline flag='s'&gt;/var/spool/jabber&lt;/jabberd:cmdline&gt;&lt;/spool&gt;
&lt;/xdb_file&gt;
&lt;/xdb&gt;
</PRE>
<!--TOC subsubsection Modules-->
<H4><A NAME="htoc18">3.1.6</A>&nbsp;&nbsp;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&nbsp;<A HREF="#sec:modules">A</A> for detailed information on each module.<BR>
<BR>
Example:
<PRE>
{modules,
[{mod_register, []},
{mod_roster, []},
{mod_privacy, []},
{mod_configure, []},
{mod_disco, []},
{mod_stats, []},
{mod_vcard, []},
{mod_offline, []},
{mod_announce, [{access, announce}]},
{mod_echo, [{host, "echo.localhost"}]},
{mod_private, []},
{mod_irc, []},
{mod_muc, []},
{mod_pubsub, []},
{mod_time, [{iqdisc, no_queue}]},
{mod_last, []},
{mod_version, []}
]}.
</PRE>
<!--TOC subsection Online Configuration and Monitoring-->
<H3><A NAME="htoc19">3.2</A>&nbsp;&nbsp;Online Configuration and Monitoring</H3><!--SEC END -->
<A NAME="sec:onlineconfig"></A>
<!--TOC subsubsection Web-based Administration Interface-->
<H4><A NAME="htoc20">3.2.1</A>&nbsp;&nbsp;Web-based Administration Interface</H4><!--SEC END -->
<A NAME="sec:webadm"></A>
To perform online reconfiguration of <TT>ejabberd</TT> you need to enable
<TT>ejabberd_http</TT> listener with option <TT>web_admin</TT> (see
section&nbsp;<A HREF="#sec:configlistened">3.1.5</A>). After that you can open URL
<CODE>http://server:port/admin/</CODE> with you favorite web-browser and enter
username and password of an <TT>ejabberd</TT> user with administrator rights. E.&nbsp;g.
with such config:
<PRE>
...
{host, "example.org"}.
...
{listen,
[...
{5280, ejabberd_http, [web_admin]},
...
]
}.
</PRE>you should enter URL <CODE>http://example.org:5280/admin/</CODE>. After
authentication you should see something like in figure&nbsp;<A HREF="#fig:webadmmain">1</A>.
<BLOCKQUOTE><DIV ALIGN=center><DIV ALIGN=center><HR WIDTH="80%" SIZE=2></DIV>
<IMG SRC="webadmmain.png">
<BR>
<DIV ALIGN=center>Figure 1: Web-administration top page</DIV><BR>
<A NAME="fig:webadmmain"></A>
<DIV ALIGN=center><HR WIDTH="80%" SIZE=2></DIV></DIV></BLOCKQUOTE>
Here you can edit access restrictions, manage users, create backup files,
manage DB, enable/disable listened ports, and view statistics.<BR>
<BR>
<!--TOC subsubsection <TT>ejabberdctl</TT> tool-->
<H4><A NAME="htoc21">3.2.2</A>&nbsp;&nbsp;<TT>ejabberdctl</TT> tool</H4><!--SEC END -->
<A NAME="sec:ejabberdctl"></A>
It is possible to do some administration operations using <TT>ejabberdctl</TT>
command-line tool. You can check available options running this command
without arguments:
<PRE>
% ejabberdctl
Usage: ejabberdctl node command
Available commands:
stop stop ejabberd
restart restart ejabberd
reopen-log reopen log file
register user password register a user
unregister user unregister a user
backup file store a database backup in file
restore file restore a database backup from file
install-fallback file install a database fallback from file
dump file dump a database in a text file
load file restore a database from a text file
registered-users list all registered users
Example:
ejabberdctl ejabberd@host restart
</PRE>
<!--TOC section Clustering-->
<H2><A NAME="htoc22">4</A>&nbsp;&nbsp;Clustering</H2><!--SEC END -->
<A NAME="sec:clustering"></A>
<!--TOC subsection How it works-->
<H3><A NAME="htoc23">4.1</A>&nbsp;&nbsp;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 runned 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="htoc24">4.1.1</A>&nbsp;&nbsp;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 uses a global
routing table. A domain of packet destination is searched in the
routing table, and if it is found, then the packet is routed to
appropriate process. If no, then it is sent to the S2S manager.<BR>
<BR>
<!--TOC subsubsection Local Router-->
<H4><A NAME="htoc25">4.1.2</A>&nbsp;&nbsp;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 is routed to the session manager, else it is processed depending on
its content.<BR>
<BR>
<!--TOC subsubsection Session Manager-->
<H4><A NAME="htoc26">4.1.3</A>&nbsp;&nbsp;Session Manager</H4><!--SEC END -->
This module routes packets to local users. It searches to what user
resource a packet must be sent via a presence table. Then packet is
either routed to appropriate C2S process, or stored in offline
storage, or bounced back.<BR>
<BR>
<!--TOC subsubsection S2S Manager-->
<H4><A NAME="htoc27">4.1.4</A>&nbsp;&nbsp;S2S Manager</H4><!--SEC END -->
This module routes packets to other Jabber servers. First, it
checks if an opened S2S connection from the domain of the packet
source to the domain of packet destination is existing. If it is
existing, then the S2S manager routes the packet to the process
serving this connection, else a new connection is opened.<BR>
<BR>
<!--TOC subsection How to setup ejabberd cluster-->
<H3><A NAME="htoc28">4.2</A>&nbsp;&nbsp;How to setup ejabberd cluster</H3><!--SEC END -->
<A NAME="sec:cluster"></A>
Suppose you already setuped ejabberd on one of machines (<TT>first</TT>), and
you need to setup another one to make <TT>ejabberd</TT> cluster. Then do
following steps:
<OL type=1><LI>
Copy <CODE>~ejabberd/.erlang.cookie</CODE> file from <TT>first</TT> to
<TT>second</TT>.<BR>
<BR>
(alt) You can also add ``<CODE>-cookie content_of_.erlang.cookie</CODE>''
option to all ``<TT>erl</TT>'' commands below.<BR>
<BR>
<LI>On <TT>second</TT> run under `<TT>ejabberd</TT>' user in a directory
where ejabberd will work later the following command:
<PRE>
erl -sname ejabberd \
-mnesia extra_db_nodes "['ejabberd@first']" \
-s mnesia
</PRE>This will start mnesia serving same DB as <TT>ejabberd@first</TT>.
You can check this running ``<CODE>mnesia:info().</CODE>'' command. You
should see a lot of remote tables and a line like the following:
<PRE>
running db nodes = [ejabberd@first, ejabberd@second]
</PRE>
<LI>Now run the following in the same ``<TT>erl</TT>'' session:
<PRE>
mnesia:change_table_copy_type(schema, node(), disc_copies).
</PRE>
This will create local disc storage for DB.<BR>
<BR>
(alt) Change storage type of `<TT>scheme</TT>' table to ``RAM and disc
copy'' on second node via web interface.<BR>
<BR>
<LI>Now you can add replicas of various tables to this node with
``<CODE>mnesia:add_table_copy</CODE>'' or
``<CODE>mnesia:change_table_copy_type</CODE>'' as above (just replace
``<CODE>schema</CODE>'' with another table name and ``<CODE>disc_copies</CODE>''
can be replaced with ``<CODE>ram_copies</CODE>'' or
``<CODE>disc_only_copies</CODE>'').<BR>
<BR>
What tables to replicate is very depend on your needs, you can get
some hints from ``<CODE>mnesia:info().</CODE>'' command, by looking at
size of tables and default storage type for each table on 'first'.<BR>
<BR>
Replicating of table makes lookup in this table faster on this node,
but writing will be slower. And of course if machine with one of
replicas is down, other replicas will be used.<BR>
<BR>
Also section ``5.3 Table Fragmentation''
<A HREF="http://www.erlang.se/doc/doc-5.4/lib/mnesia-4.2/doc/html/index.html">here</A>
can be useful.<BR>
<BR>
(alt) Same as in previous item, but for other tables.<BR>
<BR>
<LI>Run ``<CODE>init:stop().</CODE>'' or just ``<CODE>q().</CODE>'' to exit from
erlang shell. This probably can take some time if mnesia is not yet
transfer and process all data it needed from <TT>first</TT>.<BR>
<BR>
<LI>Now run ejabberd on <TT>second</TT> with almost the same config as
on <TT>first</TT> (you probably don't need to duplicate ``<CODE>acl</CODE>''
and ``<CODE>access</CODE>'' options --- they will be taken from
<TT>first</TT>, and <CODE>mod_muc</CODE> and <CODE>mod_irc</CODE> should be
enabled only on one machine in cluster).
</OL>
You can repeat these steps for other machines supposed to serve this
domain.<BR>
<BR>
<!--TOC section Built-in Modules-->
<H2><A NAME="htoc29">A</A>&nbsp;&nbsp;Built-in Modules</H2><!--SEC END -->
<A NAME="sec:modules"></A>
<!--TOC subsection Common Options-->
<H3><A NAME="htoc30">A.1</A>&nbsp;&nbsp;Common Options</H3><!--SEC END -->
<A NAME="sec:modcommonopts"></A>
The following options are used by many modules, so they are described in
separate section.<BR>
<BR>
<!--TOC subsubsection <TT>iqdisc</TT>-->
<H4><A NAME="htoc31">A.1.1</A>&nbsp;&nbsp;<TT>iqdisc</TT></H4><!--SEC END -->
<A NAME="sec:modiqdiscoption"></A>
Many modules define handlers for processing IQ queries of different namespaces
to this server or to user (e.&nbsp;g. to <TT>example.org</TT> or to
<TT>user@example.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 relatively long time.
<DT><B><TT>one_queue</TT></B><DD> In this case created separate queue for processing
of IQ queries of namespace with this discipline, and processing of this queue
is 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 relatively low cost, this can broke
server normal work, because Erlang emulator have limit on number of processes
(32000 by default).
</DL>
Example:
<PRE>
{modules,
[
...
{mod_time, [{iqdisc, no_queue}]},
...
]}.
</PRE>
<!--TOC subsubsection <TT>host</TT>-->
<H4><A NAME="htoc32">A.1.2</A>&nbsp;&nbsp;<TT>host</TT></H4><!--SEC END -->
<A NAME="sec:modhostoption"></A>
This option explicitly defines hostname for the module which acts as a service.<BR>
<BR>
Example:
<PRE>
{modules,
[
...
{mod_echo, [{host, "echo.example.org"}]},
...
]}.
</PRE>
<!--TOC subsubsection <TT>hosts</TT>-->
<H4><A NAME="htoc33">A.1.3</A>&nbsp;&nbsp;<TT>hosts</TT></H4><!--SEC END -->
<A NAME="sec:modhostsoption"></A>
This option explicitly defines a list of hostnames for the module which acts as
a service.<BR>
<BR>
Example:
<PRE>
{modules,
[
...
{mod_echo, [{hosts, ["echo.example.org", "echo.example.com"]}]},
...
]}.
</PRE>
<!--TOC subsection <TT>mod_announce</TT>-->
<H3><A NAME="htoc34">A.2</A>&nbsp;&nbsp;<TT>mod_announce</TT></H3><!--SEC END -->
<A NAME="sec:modannounce"></A>
This module adds support for broadcast announce messages and MOTD.
When the module is loaded, it handles messages sent to the following JID's
(suppose that main server has address <TT>example.org</TT>):
<DL COMPACT=compact><DT>
<B><TT>example.org/announce/all</TT></B><DD> Message is sent to all registered users at
<TT>example.org</TT>. If the user is online and connected to several resources,
only resource with the highest priority will receive the message. If the
registered user is not connected, the message will be stored offline (if
oflline storage is available).
<DT><B><TT>example.org/announce/online</TT></B><DD> Message is sent to all connected users at
<TT>example.org</TT>. If the user is online and connected to several resources,
all resources will receive the message.
<DT><B><TT>example.org/announce/all-hosts/online</TT></B><DD> Message is sent to all connected
users at every virtual host. If the user is online and connected to several
resources, all resources will receive the message.
<DT><B><TT>example.org/announce/motd</TT></B><DD> Message is set as MOTD (Message of the Day)
and is sent to users at <TT>example.org</TT> as they login. In addition the
message is sent to all connected users (similar to <TT>announce/online</TT>
resource).
<DT><B><TT>example.org/announce/motd/update</TT></B><DD> Message is set as MOTD (Message of the
Day) and is sent to users at <TT>example.org</TT> as they login. The message
is <EM>not sent</EM> to all connected users.
<DT><B><TT>example.org/announce/motd/delete</TT></B><DD> Any message sent to this JID
removes existing MOTD.
</DL>
Options:
<DL COMPACT=compact><DT>
<B><TT>access</TT></B><DD> Specifies who is allowed to send announce messages
and set MOTD (default value is <TT>none</TT>).
</DL>
Example:
<PRE>
% Only admins can send announcement messages:
{access, announce, [{allow, admin}]}.
{modules,
[
...
{mod_announce, [{access, announce}]},
...
]}.
</PRE>
<!--TOC subsection <TT>mod_configure</TT>-->
<H3><A NAME="htoc35">A.3</A>&nbsp;&nbsp;<TT>mod_configure</TT></H3><!--SEC END -->
<A NAME="sec:modconfigure"></A>
Options:
<DL COMPACT=compact><DT>
<B><TT>iqdisc</TT></B><DD> <TT>ejabberd:config</TT> IQ queries processing
discipline (see&nbsp;<A HREF="#sec:modiqdiscoption">A.1.1</A>).
</DL>
<!--TOC subsection <TT>mod_disco</TT>-->
<H3><A NAME="htoc36">A.4</A>&nbsp;&nbsp;<TT>mod_disco</TT></H3><!--SEC END -->
<A NAME="sec:moddisco"></A>
This module adds support for <A HREF="http://www.jabber.org/jeps/jep-0030.html">JEP-0030</A> (Service Discovery).<BR>
<BR>
Options:
<DL COMPACT=compact><DT>
<B><TT>iqdisc</TT></B><DD> <TT>http://jabber.org/protocol/disco#items</TT> and
<TT>http://jabber.org/protocol/disco#info</TT> IQ queries processing
discipline (see&nbsp;<A HREF="#sec:modiqdiscoption">A.1.1</A>).
<DT><B><TT>extra_domains</TT></B><DD> List of domains that will be added to server
items reply
</DL>
Example:
<PRE>
{modules,
[
...
{mod_disco, [{extra_domains, ["jit.example.com",
"etc.example.com"]}]},
...
]}.
</PRE>
<!--TOC subsection <TT>mod_echo</TT>-->
<H3><A NAME="htoc37">A.5</A>&nbsp;&nbsp;<TT>mod_echo</TT></H3><!--SEC END -->
<A NAME="sec:modecho"></A>
This module acts as a service and simply returns to sender any Jabber
packet. Module may be useful for debugging.<BR>
<BR>
Options:
<DL COMPACT=compact><DT>
<B><TT>host</TT></B><DD> Defines hostname of the service
(see&nbsp;<A HREF="#sec:modhostoption">A.1.2</A>).
<DT><B><TT>hosts</TT></B><DD> Defines hostnames of the service
(see&nbsp;<A HREF="#sec:modhostsoption">A.1.3</A>). If neither <TT>host</TT> nor <TT>hosts</TT>
are not present, then prefix <TT>echo.</TT> is added to all <TT>ejabberd</TT> hostnames.
</DL>
<!--TOC subsection <TT>mod_irc</TT>-->
<H3><A NAME="htoc38">A.6</A>&nbsp;&nbsp;<TT>mod_irc</TT></H3><!--SEC END -->
<A NAME="sec:modirc"></A>
This module implements IRC transport.<BR>
<BR>
Options:
<DL COMPACT=compact><DT>
<B><TT>host</TT></B><DD> Defines hostname of the service
(see&nbsp;<A HREF="#sec:modhostoption">A.1.2</A>).
<DT><B><TT>hosts</TT></B><DD> Defines hostnames of the service
(see&nbsp;<A HREF="#sec:modhostsoption">A.1.3</A>). If neither <TT>host</TT> nor <TT>hosts</TT>
are not present, then prefix <TT>irc.</TT> is added to all <TT>ejabberd</TT> hostnames.
<DT><B><TT>access</TT></B><DD> Specifies who is allowed to use IRC transport (default value is <TT>all</TT>).
</DL>
Example:
<PRE>
{modules,
[
...
{mod_irc, [{access, all}]},
...
]}.
</PRE>
<!--TOC subsection <TT>mod_last</TT>-->
<H3><A NAME="htoc39">A.7</A>&nbsp;&nbsp;<TT>mod_last</TT></H3><!--SEC END -->
<A NAME="sec:modlast"></A>
This module adds support for <A HREF="http://www.jabber.org/jeps/jep-0012.html">JEP-0012</A> (Last Activity)<BR>
<BR>
Options:
<DL COMPACT=compact><DT>
<B><TT>iqdisc</TT></B><DD> <TT>jabber:iq:last</TT> IQ queries processing
discipline (see&nbsp;<A HREF="#sec:modiqdiscoption">A.1.1</A>).
</DL>
<!--TOC subsection <TT>mod_muc</TT>-->
<H3><A NAME="htoc40">A.8</A>&nbsp;&nbsp;<TT>mod_muc</TT></H3><!--SEC END -->
<A NAME="sec:modmuc"></A>
This module implements <A HREF="http://www.jabber.org/jeps/jep-0045.html">JEP-0045</A> (Multi-User Chat) service.<BR>
<BR>
Options:
<DL COMPACT=compact><DT>
<B><TT>host</TT></B><DD> Defines hostname of the service
(see&nbsp;<A HREF="#sec:modhostoption">A.1.2</A>).
<DT><B><TT>hosts</TT></B><DD> Defines hostnames of the service
(see&nbsp;<A HREF="#sec:modhostsoption">A.1.3</A>). If neither <TT>host</TT> nor <TT>hosts</TT>
are not present, then prefix <TT>conference.</TT> is added to all <TT>ejabberd</TT> hostnames.
<DT><B><TT>access</TT></B><DD> Specifies who is allowed to use MUC service (default value is <TT>all</TT>).
<DT><B><TT>access_create</TT></B><DD> Specifies who is allowed to create new rooms at
MUC service (default value is <TT>all</TT>).
<DT><B><TT>access_admin</TT></B><DD> Specifies who is allowed to administrate MUC service
(default value is <TT>none</TT>, which means that only creator may administer her room).
</DL>
Example:
<PRE>
% Define admin ACL
{acl, admin, {user, "admin"}}
% Define MUC admin access rule
{access, muc_admin, [{allow, admin}]}
{modules,
[
...
{mod_muc, [{access, all},
{access_create, all},
{access_admin, muc_admin}]},
...
]}.
</PRE>
<!--TOC subsection <TT>mod_offline</TT>-->
<H3><A NAME="htoc41">A.9</A>&nbsp;&nbsp;<TT>mod_offline</TT></H3><!--SEC END -->
<A NAME="sec:modoffline"></A>
This module implements offline message storage.<BR>
<BR>
<!--TOC subsection <TT>mod_privacy</TT>-->
<H3><A NAME="htoc42">A.10</A>&nbsp;&nbsp;<TT>mod_privacy</TT></H3><!--SEC END -->
<A NAME="sec:modprivacy"></A>
This module implements Privacy Rules as defined in XMPP IM
(see <A HREF="http://www.jabber.org/ietf/"><TT>http://www.jabber.org/ietf/</TT></A>).<BR>
<BR>
Options:
<DL COMPACT=compact><DT>
<B><TT>iqdisc</TT></B><DD> <TT>jabber:iq:privacy</TT> IQ queries processing
discipline (see&nbsp;<A HREF="#sec:modiqdiscoption">A.1.1</A>).
</DL>
<!--TOC subsection <TT>mod_private</TT>-->
<H3><A NAME="htoc43">A.11</A>&nbsp;&nbsp;<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 (see&nbsp;<A HREF="#sec:modiqdiscoption">A.1.1</A>).
</DL>
<!--TOC subsection <TT>mod_pubsub</TT>-->
<H3><A NAME="htoc44">A.12</A>&nbsp;&nbsp;<TT>mod_pubsub</TT></H3><!--SEC END -->
<A NAME="sec:modpubsub"></A>
This module implements <A HREF="http://www.jabber.org/jeps/jep-0060.html">JEP-0060</A> (Publish-Subscribe Service).<BR>
<BR>
Options:
<DL COMPACT=compact><DT>
<B><TT>host</TT></B><DD> Defines hostname of the service
(see&nbsp;<A HREF="#sec:modhostoption">A.1.2</A>).
<DT><B><TT>hosts</TT></B><DD> Defines hostnames of the service
(see&nbsp;<A HREF="#sec:modhostsoption">A.1.3</A>). If neither <TT>host</TT> nor <TT>hosts</TT>
are not present, then prefix <TT>pubsub.</TT> is added to all <TT>ejabberd</TT> hostnames.
<DT><B><TT>served_hosts</TT></B><DD> Specifies which hosts are served by the service.
If absent then only main <TT>ejabberd</TT> host is served.
</DL>
Example:
<PRE>
{modules,
[
...
{mod_pubsub, [{served_hosts, ["example.com",
"example.org"]}]}
...
]}.
</PRE>
<!--TOC subsection <TT>mod_register</TT>-->
<H3><A NAME="htoc45">A.13</A>&nbsp;&nbsp;<TT>mod_register</TT></H3><!--SEC END -->
<A NAME="sec:modregister"></A>
This module adds support for <A HREF="http://www.jabber.org/jeps/jep-0077.html">JEP-0077</A> (In-Band Registration).<BR>
<BR>
Options:
<DL COMPACT=compact><DT>
<B><TT>access</TT></B><DD> Specifies rule to restrict registration.
If this rule returns ``deny'' on requested user name, then
registration is not allowed for it. (default value is <TT>all</TT>, which means
no restrictions).
<DT><B><TT>iqdisc</TT></B><DD> <TT>jabber:iq:register</TT> IQ queries processing
discipline (see&nbsp;<A HREF="#sec:modiqdiscoption">A.1.1</A>).
</DL>
Example:
<PRE>
% Deny registration for users with too short name
{acl, shortname, {user_glob, "?"}}.
{acl, shortname, {user_glob, "??"}}.
% Another variant: {acl, shortname, {user_regexp, "^..?$"}}.
{access, register, [{deny, shortname},
{allow, all}]}.
{modules,
[
...
{mod_register, [{access, register}]},
...
]}.
</PRE>
<!--TOC subsection <TT>mod_roster</TT>-->
<H3><A NAME="htoc46">A.14</A>&nbsp;&nbsp;<TT>mod_roster</TT></H3><!--SEC END -->
<A NAME="sec:modroster"></A>
This module implements roster management.<BR>
<BR>
Options:
<DL COMPACT=compact><DT>
<B><TT>iqdisc</TT></B><DD> <TT>jabber:iq:roster</TT> IQ queries processing
discipline (see&nbsp;<A HREF="#sec:modiqdiscoption">A.1.1</A>).
</DL>
<!--TOC subsection <TT>mod_service_log</TT>-->
<H3><A NAME="htoc47">A.15</A>&nbsp;&nbsp;<TT>mod_service_log</TT></H3><!--SEC END -->
<A NAME="sec:modservicelog"></A>
This module adds support for logging of user packets via any jabber service.
These packets encapsulated in &lt;route/&gt; element and sended to specified
services.<BR>
<BR>
Options:
<DL COMPACT=compact><DT>
<B><TT>loggers</TT></B><DD> Specifies a list of services which will receive users
packets.
</DL>
Example:
<PRE>
{modules,
[
...
{mod_service_log, [{loggers, ["bandersnatch.example.com"]}]},
...
]}.
</PRE>
<!--TOC subsection <TT>mod_shared_roster</TT>-->
<H3><A NAME="htoc48">A.16</A>&nbsp;&nbsp;<TT>mod_shared_roster</TT></H3><!--SEC END -->
<A NAME="sec:modsharedroster"></A>
This module implements shared roster groups support.<BR>
<BR>
You can edit shared roster groups via web-interface. Each group has an unique
ID and the following parameters:
<DL COMPACT=compact><DT>
<B>Name</B><DD> The name of the group, which will be displayed in roster.
<DT><B>Description</B><DD> Textual description of this group, doesn't affect anything.
<DT><B>Members</B><DD> List of full JIDs of group members, entered one per line in
web-interface.
<DT><B>Displayed groups</B><DD> List of IDs of groups which will be in rosters of this
group members.
</DL>
For example, to have a group of users which can see each other in roster,
create a group like on table&nbsp;<A HREF="#tab:srge1">1</A>.
<BLOCKQUOTE><DIV ALIGN=center><DIV ALIGN=center><HR WIDTH="80%" SIZE=2></DIV>
<TABLE BORDER=1 CELLSPACING=0 CELLPADDING=1>
<TR><TD ALIGN=left NOWRAP>&nbsp;</TD>
<TD ALIGN=left NOWRAP>Group `<TT>users</TT>'</TD>
</TR>
<TR><TD ALIGN=left NOWRAP>Name</TD>
<TD ALIGN=left NOWRAP>Users</TD>
</TR>
<TR><TD ALIGN=left NOWRAP>Members</TD>
<TD ALIGN=left NOWRAP><TABLE CELLSPACING=2 CELLPADDING=0>
<TR><TD ALIGN=left NOWRAP><TT>user1@example.org</TT></TD>
</TR>
<TR><TD ALIGN=left NOWRAP><TT>user2@example.org</TT></TD>
</TR>
<TR><TD ALIGN=left NOWRAP><TT>user3@example.org</TT></TD>
</TR></TABLE></TD>
</TR>
<TR><TD ALIGN=left NOWRAP>Displayed groups</TD>
<TD ALIGN=left NOWRAP><TT>users</TT></TD>
</TR></TABLE>
<BR>
<DIV ALIGN=center>Table 1: Shared group example N1</DIV><BR>
<A NAME="tab:srge1"></A>
<DIV ALIGN=center><HR WIDTH="80%" SIZE=2></DIV></DIV></BLOCKQUOTE>
To have 3 groups `<TT>managers</TT>', `<TT>workgroup1</TT>', and
`<TT>workgroup2</TT>', where group `<TT>managers</TT>' can see members of all
groups, and other two groups can see `<TT>managers</TT>' group and themselves,
create groups like on table&nbsp;<A HREF="#tab:srge2">2</A>.
<BLOCKQUOTE><DIV ALIGN=center><DIV ALIGN=center><HR WIDTH="80%" SIZE=2></DIV>
<TABLE BORDER=1 CELLSPACING=0 CELLPADDING=1>
<TR><TD ALIGN=left NOWRAP>&nbsp;</TD>
<TD ALIGN=left NOWRAP>Group `<TT>managers</TT>'</TD>
<TD ALIGN=left NOWRAP>Group `<TT>workgroup1</TT>'</TD>
<TD ALIGN=left NOWRAP>Group `<TT>workgroup2</TT>'</TD>
</TR>
<TR><TD ALIGN=left NOWRAP>Name</TD>
<TD ALIGN=left NOWRAP>Managers</TD>
<TD ALIGN=left NOWRAP>Workgroup1</TD>
<TD ALIGN=left NOWRAP>Workgroup2</TD>
</TR>
<TR><TD ALIGN=left NOWRAP>Members</TD>
<TD ALIGN=left NOWRAP><TABLE CELLSPACING=2 CELLPADDING=0>
<TR><TD ALIGN=left NOWRAP><TT>manager1@example.org</TT></TD>
</TR>
<TR><TD ALIGN=left NOWRAP><TT>manager2@example.org</TT></TD>
</TR>
<TR><TD ALIGN=left NOWRAP><TT>manager3@example.org</TT></TD>
</TR></TABLE>
</TD>
<TD ALIGN=left NOWRAP><TABLE CELLSPACING=2 CELLPADDING=0>
<TR><TD ALIGN=left NOWRAP><TT>user1@example.org</TT></TD>
</TR>
<TR><TD ALIGN=left NOWRAP><TT>user2@example.org</TT></TD>
</TR>
<TR><TD ALIGN=left NOWRAP><TT>user3@example.org</TT></TD>
</TR></TABLE>
</TD>
<TD ALIGN=left NOWRAP><TABLE CELLSPACING=2 CELLPADDING=0>
<TR><TD ALIGN=left NOWRAP><TT>user4@example.org</TT></TD>
</TR>
<TR><TD ALIGN=left NOWRAP><TT>user5@example.org</TT></TD>
</TR>
<TR><TD ALIGN=left NOWRAP><TT>user6@example.org</TT></TD>
</TR></TABLE></TD>
</TR>
<TR><TD ALIGN=left NOWRAP>Displayed groups</TD>
<TD ALIGN=left NOWRAP><TABLE CELLSPACING=2 CELLPADDING=0>
<TR><TD ALIGN=left NOWRAP><TT>managers</TT></TD>
</TR>
<TR><TD ALIGN=left NOWRAP><TT>workgroup1</TT></TD>
</TR>
<TR><TD ALIGN=left NOWRAP><TT>workgroup2</TT></TD>
</TR></TABLE>
</TD>
<TD ALIGN=left NOWRAP><TABLE CELLSPACING=2 CELLPADDING=0>
<TR><TD ALIGN=left NOWRAP><TT>managers</TT></TD>
</TR>
<TR><TD ALIGN=left NOWRAP><TT>workgroup1</TT></TD>
</TR></TABLE>
</TD>
<TD ALIGN=left NOWRAP><TABLE CELLSPACING=2 CELLPADDING=0>
<TR><TD ALIGN=left NOWRAP><TT>managers</TT></TD>
</TR>
<TR><TD ALIGN=left NOWRAP><TT>workgroup2</TT></TD>
</TR></TABLE></TD>
</TR></TABLE>
<BR>
<DIV ALIGN=center>Table 2: Shared group example N2</DIV><BR>
<A NAME="tab:srge2"></A>
<DIV ALIGN=center><HR WIDTH="80%" SIZE=2></DIV></DIV></BLOCKQUOTE>
<!--TOC subsection <TT>mod_stats</TT>-->
<H3><A NAME="htoc49">A.17</A>&nbsp;&nbsp;<TT>mod_stats</TT></H3><!--SEC END -->
<A NAME="sec:modstats"></A>
This module adds support for <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 (see&nbsp;<A HREF="#sec:modiqdiscoption">A.1.1</A>).
</DL>
<!--TOC subsection <TT>mod_time</TT>-->
<H3><A NAME="htoc50">A.18</A>&nbsp;&nbsp;<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 (see&nbsp;<A HREF="#sec:modiqdiscoption">A.1.1</A>).
</DL>
<!--TOC subsection <TT>mod_vcard</TT>-->
<H3><A NAME="htoc51">A.19</A>&nbsp;&nbsp;<TT>mod_vcard</TT></H3><!--SEC END -->
<A NAME="sec:modvcard"></A>
This module implements simple Jabber User Directory (based on user vCards)
and answers server vCard on <TT>vcard-temp</TT> queries.<BR>
<BR>
Options:
<DL COMPACT=compact><DT>
<B><TT>host</TT></B><DD> Defines hostname of the service
(see&nbsp;<A HREF="#sec:modhostoption">A.1.2</A>).
<DT><B><TT>hosts</TT></B><DD> Defines hostnames of the service
(see&nbsp;<A HREF="#sec:modhostsoption">A.1.3</A>). If neither <TT>host</TT> nor <TT>hosts</TT>
are not present, then prefix <TT>vjud.</TT> is added to all <TT>ejabberd</TT> hostnames.
<DT><B><TT>iqdisc</TT></B><DD> <TT>vcard-temp</TT> IQ queries processing
discipline (see&nbsp;<A HREF="#sec:modiqdiscoption">A.1.1</A>).
<DT><B><TT>search</TT></B><DD> Specifies whether search is enabled (value is <TT>true</TT>, default) or
disabled (value is <TT>false</TT>) by the service. If <TT>search</TT> is set to <TT>false</TT>,
option <TT>host</TT> is ignored and service does not appear in Jabber Discovery items.
<DT><B><TT>matches</TT></B><DD> Limits the number of reported search results. If value is set to
<TT>infinity</TT> then all search results are reported. Default value is <TT>30</TT>.
<DT><B><TT>allow_return_all</TT></B><DD> Specifies whether search with empty input fields can
return all known users. Default is <TT>false</TT>.
<DT><B><TT>search_all_hosts</TT></B><DD> If set in <TT>true</TT> then search returns matched
items at all virtual hosts. Otherwise only current host items are returned.
Default is <TT>true</TT>.
</DL>
Example:
<PRE>
{modules,
[
...
{mod_vcard, [{search, true},
{matches, 20},
{allow_return_all, true},
{search_all_hosts, false}]}
...
]}.
</PRE>
<!--TOC subsection <TT>mod_version</TT>-->
<H3><A NAME="htoc52">A.20</A>&nbsp;&nbsp;<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 (see&nbsp;<A HREF="#sec:modiqdiscoption">A.1.1</A>).
</DL>
<!--TOC section I18n/L10n-->
<H2><A NAME="htoc53">B</A>&nbsp;&nbsp;I18n/L10n</H2><!--SEC END -->
<A NAME="sec:i18nl10n"></A>
All built-in modules support <TT>xml:lang</TT> attribute inside IQ queries.
E.&nbsp;g. on figure&nbsp;<A HREF="#fig:discorus">2</A> showed the reply on the following query:
<PRE>
&lt;iq id='5'
to='e.localhost'
type='get'
xml:lang='ru'&gt;
&lt;query xmlns='http://jabber.org/protocol/disco#items'/&gt;
&lt;/iq&gt;
</PRE>
<BLOCKQUOTE><DIV ALIGN=center><DIV ALIGN=center><HR WIDTH="80%" SIZE=2></DIV>
<IMG SRC="discorus.png">
<BR>
<DIV ALIGN=center>Figure 2: 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>
Also web-interface supports <CODE>Accept-Language</CODE> HTTP header (see
figure&nbsp;<A HREF="#fig:webadmmainru">3</A>, compare it with figure&nbsp;<A HREF="#fig:webadmmain">1</A>)
<BLOCKQUOTE><DIV ALIGN=center><DIV ALIGN=center><HR WIDTH="80%" SIZE=2></DIV>
<IMG SRC="webadmmainru.png">
<BR>
<DIV ALIGN=center>Figure 3: Web-administration top page with HTTP header
``<CODE>Accept-Language: ru</CODE>''</DIV><BR>
<A NAME="fig:webadmmainru"></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>
View Git Blame Copy Permalink