25
1
mirror of https://github.com/processone/ejabberd.git synced 2024-12-22 17:28:25 +01:00
xmpp.chapril.org-ejabberd/doc/guide.html

420 lines
14 KiB
HTML
Raw Normal View 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=ISO-8859-1">
<META name="GENERATOR" content="hevea 1.05">
</HEAD>
<BODY >
<!--HEVEA command line is: hevea guide.tex -->
<!--HTMLHEAD-->
<!--ENDHTML-->
<!--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>January 26, 2003</H3> <DIV ALIGN=center><IMG SRC="logo.png">
</DIV><BR>
<BR>
<BR>
<BR>
<!--TOC section Introduction-->
<H2>1&nbsp;&nbsp; Introduction</H2><!--SEC END -->
<A NAME="sec:intro"></A><TT>ejabberd</TT> is a Free and Open Source distributed fault-tolerant Jabber
server. It writen mostly in Erlang.<BR>
<BR>
TBD<BR>
<BR>
<!--TOC section Installation-->
<H2>2&nbsp;&nbsp; Installation</H2><!--SEC END -->
<A NAME="sec:installation"></A><!--TOC subsection Installation Requirements-->
<H3>2.1&nbsp;&nbsp; Installation Requirements</H3><!--SEC END -->
<A NAME="sec:installreq"></A>To compile <TT>ejabberd</TT>, you need following packages:
<UL>
<LI>
GNU Make;
<LI> GCC;
<LI> libexpat 1.95 or later;
<LI> Erlang/OTP R8B or later.
</UL><!--TOC subsection Obtaining-->
<H3>2.2&nbsp;&nbsp; Obtaining</H3><!--SEC END -->
<A NAME="sec:obtaining"></A>Currently no stable version released.<BR>
<BR>
Latest alpha version can be retrieved via CVS. Do following steps:
<UL>
<LI>
<TT>export CVSROOT=:pserver:cvs@www.jabber.ru:/var/spool/cvs</TT>
<LI> <TT>cvs login</TT>
<LI> Enter empty password
<LI> <TT>cvs -z3 co ejabberd</TT>
</UL><!--TOC subsection Compilation-->
<H3>2.3&nbsp;&nbsp; Compilation</H3><!--SEC END -->
<A NAME="sec:compilation"></A><PRE>
./configure
make
</PRE>TBD<BR>
<BR>
<!--TOC subsection Starting-->
<H3>2.4&nbsp;&nbsp; Starting</H3><!--SEC END -->
<A NAME="sec:starting"></A><PRE>
erl -name ejabberd -s ejabberd
</PRE>TBD<BR>
<BR>
<!--TOC section Configuration-->
<H2>3&nbsp;&nbsp; Configuration</H2><!--SEC END -->
<A NAME="sec:configuration"></A><!--TOC subsection Initial Configuration-->
<H3>3.1&nbsp;&nbsp; Initial Configuration</H3><!--SEC END -->
<A NAME="sec:initconfig"></A>Configuration file is loaded after first start of <TT>ejabberd</TT>. It consists of
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.<BR>
<BR>
<!--TOC subsubsection Host Name-->
<H4>3.1.1&nbsp;&nbsp; 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.&nbsp;g. to use <TT>jabber.org</TT> domain add following line in config:
<PRE>
{host, "jabber.org"}.
</PRE><!--TOC subsubsection Listened Sockets-->
<H4>3.1.2&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> Function in this module that starts connection (likely will be removed);
<LI> Options to this module.
</UL>Currently three modules implemented:
<UL>
<LI>
<TT>ejabberd_c2s</TT>: serves C2S connections;
<LI> <TT>ejabberd_s2s_in</TT>: serves incoming S2S connections;
<LI> <TT>ejabberd_service</TT>: serves connections to Jabber services
(i.&nbsp;e. that use <TT>jabber:component:accept</TT> namespace).
</UL>For example, following configuration defines that C2S connections listened on
port 5222, S2S on port 5269 and that service <TT>conference.jabber.org</TT>
must be connected to port 8888 with password ``<TT>secret</TT>''.<BR>
<BR>
<PRE>
{listen, [{5222, ejabberd_c2s, start, []},
{5269, ejabberd_s2s_in, start, []},
{8888, ejabberd_service, start, ["conference.jabber.org", "secret"]}
]}.
</PRE><!--TOC subsubsection Access Rules-->
<H4>3.1.3&nbsp;&nbsp; Access Rules</H4><!--SEC END -->
<A NAME="sec:configaccess"></A>Access control in <TT>ejabberd</TT> is done via Access Control Lists (ACL). In
config file they looks like this:
<PRE>
{acl, &lt;aclname&gt;, {&lt;acltype&gt;, ...}}.
</PRE><TT>&lt;acltype&gt;</TT> can be one of following:
<DL COMPACT=compact>
<DT>
<TT>all</TT><DD> Matches all JIDs. Example:
<PRE>
{acl, all, all}.
</PRE>
<DT><TT>{user, &lt;username&gt;}</TT><DD> Matches local user with name
<TT>&lt;username&gt;</TT>. Example:
<PRE>
{acl, admin, {user, "aleksey"}}.
</PRE>
<DT><TT>{user, &lt;username&gt;, &lt;server&gt;}</TT><DD> Matches user with JID
<TT>&lt;username&gt;@&lt;server&gt;</TT>. Example:
<PRE>
{acl, admin, {user, "aleksey", "jabber.ru"}}.
</PRE>
<DT><TT>{server, &lt;server&gt;}</TT><DD> Matches any JID from server
<TT>&lt;server&gt;</TT>. Example:
<PRE>
{acl, jabberorg, {server, "jabber.org"}}.
</PRE></DL>Allowing or denying of different services is like this:
<PRE>
{access, &lt;accessname&gt;, [{allow, &lt;aclname&gt;},
{deny, &lt;aclname&gt;},
...
]}.
</PRE>When JID is checked to have access to <TT>&lt;accessname&gt;</TT>, server
sequentially checks if this JID in one of the ACLs that are second elements in
eache tuple in list. If one of them matched, then returned first element of
matched tuple. Else returned ``<TT>deny</TT>''.<BR>
<BR>
Example:
<PRE>
{access, configure, [{allow, admin}]}.
{access, something, [{deny, badmans},
{allow, all}]}.
</PRE><!--TOC subsubsection Modules-->
<H4>3.1.4&nbsp;&nbsp; Modules</H4><!--SEC END -->
<A NAME="sec:configmodules"></A>Option <TT>modules</TT> defines 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 module and second is list of options to this module. See
section&nbsp;<A HREF="#sec:modules">5</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-->
<H3>3.2&nbsp;&nbsp; Online Configuration</H3><!--SEC END -->
<A NAME="sec:onlineconfig"></A>To use facility of online reconfiguration of <TT>ejabberd</TT> needed to have
<TT>mod_configure</TT> loaded (see section&nbsp;<A HREF="#sec:modconfigure">5.4</A>). Also highly
recommended to load <TT>mod_disco</TT> (see section&nbsp;<A HREF="#sec:moddisco">5.5</A>), because
<TT>mod_configure</TT> highly integrates with it. Also recommended to use
disco- and xdata-capable client.<BR>
<BR>
TBD<BR>
<BR>
<!--TOC section Distribution-->
<H2>4&nbsp;&nbsp; Distribution</H2><!--SEC END -->
<A NAME="sec:distribution"></A><!--TOC subsection How it works-->
<H3>4.1&nbsp;&nbsp; How it works</H3><!--SEC END -->
<A NAME="sec:howitworks"></A>Jabber domain is served by one or more <TT>ejabberd</TT> nodes. This nodes can be
runned on different machines that can be connected via network. They all must
have access to connect to port 4369 of all another nodes, and must have same
magic cookie (see Erlang/OTP documentation, in short 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
connection, registered services, etc...<BR>
<BR>
Each <TT>ejabberd</TT> node run following modules:
<UL>
<LI>
router;
<LI> local router.
<LI> session manager;
<LI> S2S manager;
</UL><!--TOC subsubsection Router-->
<H4>4.1.1&nbsp;&nbsp; Router</H4><!--SEC END -->
This module is the main router of Jabber packets on each node. It route
them based on their destanations domains. It have two tables: local and global
routes. First, domain of packet destination searched in local table, and if it
finded, then packet routed to appropriate process. If no, then it searched in
global table, and routed to appropriate <TT>ejabberd</TT> node or process. If it not
exists in both tables, then it sended to S2S manager.<BR>
<BR>
<!--TOC subsubsection Local Router-->
<H4>4.1.2&nbsp;&nbsp; Local Router</H4><!--SEC END -->
This module route packets which have destination domain equal to this server
name. If destination JID have node, then it routed to session manager, else it
processed depending on it content.<BR>
<BR>
<!--TOC subsubsection Session Manager-->
<H4>4.1.3&nbsp;&nbsp; Session Manager</H4><!--SEC END -->
This module route packets to local users. It search to what user resource
packet must be sended via presence table. If this reseouce connected to this
node, it routed to C2S process, if it connected via another node, then packet
sended to session manager on it.<BR>
<BR>
<!--TOC subsubsection S2S Manager-->
<H4>4.1.4&nbsp;&nbsp; S2S Manager</H4><!--SEC END -->
This module route packets to another Jabber servers. First, it check if
to domain of packet destination from domain of source already opened S2S
connection. If it opened on another node, then it routed to S2S manager on
that node, if it opened on this node, then it routed to process that serve this
connection, and if this connection not exists, then it opened and registered.<BR>
<BR>
<!--TOC section Built-in Modules-->
<H2>5&nbsp;&nbsp; Built-in Modules</H2><!--SEC END -->
<A NAME="sec:modules"></A><!--TOC subsection Common Options-->
<H3>5.1&nbsp;&nbsp; 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>5.1.1&nbsp;&nbsp; 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.&nbsp;g. to <TT>myjabber.org</TT> or to
<TT>user@myjabber.org</TT>). This option defines processing discipline of this
queries. Possible values are:
<DL COMPACT=compact>
<DT>
<TT>no_queue</TT><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><TT>one_queue</TT><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><TT>parallel</TT><DD> In this case for all packets of namespace with this
discipline spawned separate Erlang process, so all this 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>5.1.2&nbsp;&nbsp; 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>5.2&nbsp;&nbsp; <TT>mod_register</TT></H3><!--SEC END -->
<A NAME="sec:modregister"></A><!--TOC subsection <TT>mod_roster</TT>-->
<H3>5.3&nbsp;&nbsp; <TT>mod_roster</TT></H3><!--SEC END -->
<A NAME="sec:modroster"></A><!--TOC subsection <TT>mod_configure</TT>-->
<H3>5.4&nbsp;&nbsp; <TT>mod_configure</TT></H3><!--SEC END -->
<A NAME="sec:modconfigure"></A><!--TOC subsection <TT>mod_disco</TT>-->
<H3>5.5&nbsp;&nbsp; <TT>mod_disco</TT></H3><!--SEC END -->
<A NAME="sec:moddisco"></A><!--TOC subsection <TT>mod_stats</TT>-->
<H3>5.6&nbsp;&nbsp; <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>
<TT>iqdisc</TT><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>5.7&nbsp;&nbsp; <TT>mod_vcard</TT></H3><!--SEC END -->
<A NAME="sec:modvcard"></A><!--TOC subsection <TT>mod_offline</TT>-->
<H3>5.8&nbsp;&nbsp; <TT>mod_offline</TT></H3><!--SEC END -->
<A NAME="sec:modoffline"></A><!--TOC subsection <TT>mod_echo</TT>-->
<H3>5.9&nbsp;&nbsp; <TT>mod_echo</TT></H3><!--SEC END -->
<A NAME="sec:modecho"></A><!--TOC subsection <TT>mod_private</TT>-->
<H3>5.10&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>
<TT>iqdisc</TT><DD> <TT>jabber:iq:private</TT> IQ queries processing discipline.
</DL><!--TOC subsection <TT>mod_time</TT>-->
<H3>5.11&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>
<TT>iqdisc</TT><DD> <TT>jabber:iq:time</TT> IQ queries processing discipline.
</DL><!--TOC subsection <TT>mod_version</TT>-->
<H3>5.12&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>
<TT>iqdisc</TT><DD> <TT>jabber:iq:version</TT> IQ queries processing discipline.
</DL><!--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</EM><EM><FONT SIZE=2><sup>E</sup></FONT></EM><EM>V</EM><EM><FONT SIZE=2><sup>E</sup></FONT></EM><EM>A</EM></A><EM>.
</EM></BLOCKQUOTE></BODY>
</HTML>