mirror of
https://github.com/processone/ejabberd.git
synced 2024-12-26 17:38:45 +01:00
5c0ba6e337
* src/ejabberd_s2s_out.erl: Added support for IPv6 and "_jabber-server.tcp" lookups * src/jlib.erl (string_to_jid1): Bugfix * src/ejabberd_config.erl: Now possible to specify path to config file in command line SVN Revision: 149
882 lines
25 KiB
TeX
882 lines
25 KiB
TeX
\documentclass[10pt]{article}
|
|
|
|
\usepackage{graphics}
|
|
\usepackage{hevea}
|
|
\usepackage{verbatim}
|
|
|
|
|
|
\newcommand{\logoscale}{0.7}
|
|
\newcommand{\imgscale}{0.58}
|
|
\newcommand{\insimg}[1]{\insscaleimg{\imgscale}{#1}}
|
|
|
|
\newcommand{\insscaleimg}[2]{
|
|
\imgsrc{#2}{}
|
|
\begin{latexonly}
|
|
\scalebox{#1}{\includegraphics{#2}}
|
|
\end{latexonly}
|
|
}
|
|
|
|
\newcommand{\ns}[1]{\texttt{#1}}
|
|
\newcommand{\ejabberd}{\texttt{ejabberd}}
|
|
\newcommand{\Jabber}{Jabber}
|
|
|
|
\newcommand{\modregister}{\texttt{mod\_register}}
|
|
\newcommand{\modroster}{\texttt{mod\_roster}}
|
|
\newcommand{\modconfigure}{\texttt{mod\_configure}}
|
|
\newcommand{\moddisco}{\texttt{mod\_disco}}
|
|
\newcommand{\modstats}{\texttt{mod\_stats}}
|
|
\newcommand{\modvcard}{\texttt{mod\_vcard}}
|
|
\newcommand{\modoffline}{\texttt{mod\_offline}}
|
|
\newcommand{\modecho}{\texttt{mod\_echo}}
|
|
\newcommand{\modprivate}{\texttt{mod\_private}}
|
|
\newcommand{\modtime}{\texttt{mod\_time}}
|
|
\newcommand{\modversion}{\texttt{mod\_version}}
|
|
c
|
|
%\setcounter{tocdepth}{3}
|
|
|
|
|
|
\title{Ejabberd Installation and Operation Guide}
|
|
\author{Alexey Shchepin \\
|
|
\ahrefurl{mailto:alexey@sevcom.net} \\
|
|
\ahrefurl{xmpp:aleksey@jabber.ru}}
|
|
\date{July 12, 2003}
|
|
|
|
\begin{document}
|
|
\begin{titlepage}
|
|
\maketitle{}
|
|
|
|
{\centering
|
|
\insscaleimg{\logoscale}{logo.png}
|
|
\par
|
|
}
|
|
\end{titlepage}
|
|
%\newpage
|
|
\tableofcontents{}
|
|
|
|
\newpage
|
|
\section{Introduction}
|
|
\label{sec:intro}
|
|
|
|
\ejabberd{} is a Free and Open Source fault-tolerant distributed \Jabber{}
|
|
server. It is writen mostly in Erlang.
|
|
|
|
The main features of \ejabberd{} is:
|
|
\begin{itemize}
|
|
\item Works on most of popular platforms: *nix (tested on Linux, FreeBSD and
|
|
NetBSD) and Win32
|
|
\item Distributed: You can run \ejabberd{} on a cluster of machines and all of
|
|
them will serve one Jabber domain.
|
|
\item Fault-tolerance: You can setup an \ejabberd{} 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''.
|
|
\item Built-in \footahref{http://www.jabber.org/jeps/jep-0045.html}{Multi-User
|
|
Chat} service
|
|
\item Built-in IRC transport
|
|
\item Built-in
|
|
\footahref{http://www.jabber.org/jeps/jep-0060.html}{Publish-Subscribe}
|
|
service
|
|
\item Built-in Jabber Users Directory service based on users vCards
|
|
\item Support for
|
|
\footahref{http://www.jabber.org/jeps/jep-0030.html}{JEP-0030}
|
|
(Service Discovery).
|
|
\item Support for
|
|
\footahref{http://www.jabber.org/jeps/jep-0039.html}{JEP-0039}
|
|
(Statistics Gathering).
|
|
\item Support for \ns{xml:lang} attribute in many XML elements
|
|
\end{itemize}
|
|
|
|
|
|
|
|
|
|
\section{Installation}
|
|
\label{sec:installation}
|
|
|
|
|
|
\subsection{Installation Requirements}
|
|
\label{sec:installreq}
|
|
|
|
\subsubsection{Unix}
|
|
\label{sec:installrequnix}
|
|
|
|
To compile \ejabberd{}, you will need the following packages:
|
|
\begin{itemize}
|
|
\item GNU Make;
|
|
\item GCC;
|
|
\item libexpat 1.95 or later;
|
|
\item Erlang/OTP R8B or later.
|
|
\end{itemize}
|
|
|
|
\subsubsection{Windows}
|
|
\label{sec:installreqwin}
|
|
|
|
To compile \ejabberd{} in MS Windows environment, you will need the following
|
|
packages:
|
|
\begin{itemize}
|
|
\item MS Visual C++~6.0 Compiler
|
|
\item \footahref{http://www.erlang.org/download/otp_win32_R8B-2.exe}{Erlang
|
|
emulator version~5.1.2}
|
|
\item \footahref{http://prdownloads.sourceforge.net/expat/expat_win32bin_1_95_6.exe?download}{Expat~1.95.6}
|
|
\item \footahref{http://prdownloads.sourceforge.net/gnuwin32/libiconv-1.8-1-lib.exe?download}{Iconv~1.8} (optional)
|
|
\end{itemize}
|
|
|
|
|
|
|
|
\subsection{Obtaining}
|
|
\label{sec:obtaining}
|
|
|
|
Currently no stable version has been released.
|
|
|
|
The latest alpha version can be retrieved from CVS\@.
|
|
\begin{itemize}
|
|
\item \texttt{export CVSROOT=:pserver:anonymous@jabberstudio.org:/home/cvs}
|
|
\item \texttt{cvs login}
|
|
\item Press Enter when asked for a password
|
|
\item \texttt{cvs -z3 co ejabberd}
|
|
\end{itemize}
|
|
|
|
|
|
|
|
\subsection{Compilation}
|
|
\label{sec:compilation}
|
|
\subsubsection{Unix}
|
|
\label{sec:compilationunix}
|
|
|
|
\begin{verbatim}
|
|
./configure
|
|
make
|
|
\end{verbatim}
|
|
|
|
TBD
|
|
|
|
\subsubsection{Windows}
|
|
\label{sec:compilationwin}
|
|
|
|
\begin{enumerate}
|
|
\item Install Erlang emulator (for example, into \verb|C:\Program Files\erl5.1.2|).
|
|
\item Install Expat library into \verb|C:\Program Files\Expat-1.95.6|
|
|
directory. Copy file \verb|C:\Program Files\Expat-1.95.6\Libs\libexpat.dll|
|
|
to your Windows system directory (for example, \verb|C:\WINNT| or
|
|
\verb|C:\WINNT\System32|)
|
|
\item Install Iconv library into \verb|C:\Program Files\GnuWin32| directory.
|
|
Copy file \verb|C:\Program Files\GnuWin32\bin\libiconv-2.dll| to your
|
|
Windows system directory.
|
|
|
|
Note: Instead of copying libexpat.dll and libiconv-2.dll to Windows
|
|
directory, you can add directories
|
|
\verb|C:\Program Files\Expat-1.95.6\Libs| and
|
|
\verb|C:\Program Files\GnuWin32\bin| to \verb|PATH| environment
|
|
variable.
|
|
\item Being in \verb|ejabberd\src| directory run:
|
|
\begin{verbatim}
|
|
configure
|
|
nmake -f Makefile.win32
|
|
\end{verbatim}
|
|
\item To build MUC, IRC and pub/sub modules run
|
|
\begin{verbatim}
|
|
nmake -f Makefile.win32
|
|
\end{verbatim}
|
|
in \verb|ejabberd\src\mod_muc|, \verb|ejabberd\src\mod_muc| and
|
|
\verb|ejabberd\src\mod_pubsub| directories
|
|
\item Edit file \verb|ejabberd\src\ejabberd.cfg| and run
|
|
\begin{verbatim}
|
|
werl -s ejabberd -name ejabberd
|
|
\end{verbatim}
|
|
\item Enjoy!
|
|
\end{enumerate}
|
|
|
|
Some recent versions of Erlang distribution it seems have bug in crypto
|
|
application, so ejabberd could be built but users can't use digest
|
|
authentication (only plain-text). Also it seems SSL support is broken in
|
|
Windows distribution of Erlang emulator.
|
|
|
|
|
|
|
|
|
|
%\subsection{Initial Configuration}
|
|
%\label{sec:initconfig}
|
|
|
|
|
|
\subsection{Starting}
|
|
\label{sec:starting}
|
|
|
|
To start \ejabberd{}, use the following command:
|
|
\begin{verbatim}
|
|
erl -name ejabberd -s ejabberd
|
|
\end{verbatim}
|
|
or
|
|
\begin{verbatim}
|
|
erl -sname ejabberd -s ejabberd
|
|
\end{verbatim}
|
|
In second case Erlang node will be identified using only first part of host
|
|
name, i.\,e. other Erlang nodes not inside this domain can't contact this node.
|
|
|
|
To specify path to config file, use command like this:
|
|
\begin{verbatim}
|
|
erl -sname ejabberd -s ejabberd -ejabberd config \"/etc/ejabberd/ejabberd.cfg\"
|
|
\end{verbatim}
|
|
|
|
|
|
To use more than 1024 connections, you will need to set environment variable
|
|
\verb|ERL_MAX_PORTS|:
|
|
\begin{verbatim}
|
|
export ERL_MAX_PORTS=32000
|
|
\end{verbatim}
|
|
Note that with this value \ejabberd{} will use more memory (approximately 6MB
|
|
more).
|
|
|
|
To reduce memory usage, you can set environment variable
|
|
\verb|ERL_FULLSWEEP_AFTER|:
|
|
\begin{verbatim}
|
|
export ERL_FULLSWEEP_AFTER=0
|
|
\end{verbatim}
|
|
But in this case \ejabberd{} can start to work slower.
|
|
|
|
|
|
|
|
|
|
\section{Configuration}
|
|
\label{sec:configuration}
|
|
|
|
\subsection{Initial Configuration}
|
|
\label{sec:initconfig}
|
|
|
|
%\verbatiminput{../src/ejabberd.cfg}
|
|
|
|
The configuration file is initially loaded the first time \ejabberd{} 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 \texttt{`\%'} 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.
|
|
|
|
|
|
To override old values stored in the database the following lines can be added
|
|
in config:
|
|
\begin{verbatim}
|
|
override_global.
|
|
override_local.
|
|
override_acls.
|
|
\end{verbatim}
|
|
With this lines old global or local options or ACLs will be removed before
|
|
adding new ones.
|
|
|
|
|
|
\subsubsection{Host Name}
|
|
\label{sec:confighostname}
|
|
|
|
Option \texttt{hostname} defines name of \Jabber{} domain that \ejabberd{}
|
|
serves. E.\,g.\ to use \texttt{jabber.org} domain add following line in config:
|
|
\begin{verbatim}
|
|
{host, "jabber.org"}.
|
|
\end{verbatim}
|
|
|
|
%This option is mandatory.
|
|
|
|
|
|
|
|
\subsubsection{Access Rules}
|
|
\label{sec:configaccess}
|
|
|
|
Access control in \ejabberd{} is performed via Access Control Lists (ACL). The
|
|
declarations of ACL in config file have following syntax:
|
|
\begin{verbatim}
|
|
{acl, <aclname>, {<acltype>, ...}}.
|
|
\end{verbatim}
|
|
|
|
\texttt{<acltype>} can be one of following:
|
|
\begin{description}
|
|
\item[\texttt{all}] Matches all JIDs. Example:
|
|
\begin{verbatim}
|
|
{acl, all, all}.
|
|
\end{verbatim}
|
|
\item[\texttt{\{user, <username>\}}] Matches local user with name
|
|
\texttt{<username>}. Example:
|
|
\begin{verbatim}
|
|
{acl, admin, {user, "aleksey"}}.
|
|
\end{verbatim}
|
|
\item[\texttt{\{user, <username>, <server>\}}] Matches user with JID
|
|
\texttt{<username>@<server>} and any resource. Example:
|
|
\begin{verbatim}
|
|
{acl, admin, {user, "aleksey", "jabber.ru"}}.
|
|
\end{verbatim}
|
|
\item[\texttt{\{server, <server>\}}] Matches any JID from server
|
|
\texttt{<server>}. Example:
|
|
\begin{verbatim}
|
|
{acl, jabberorg, {server, "jabber.org"}}.
|
|
\end{verbatim}
|
|
\item[\texttt{\{user\_regexp, <regexp>\}}] Matches local user with name that
|
|
matches \texttt{<regexp>}. Example:
|
|
\begin{verbatim}
|
|
{acl, tests, {user, "^test[0-9]*$"}}.
|
|
\end{verbatim}
|
|
%$
|
|
\item[\texttt{\{user\_regexp, <regexp>, <server>\}}] Matches user with name
|
|
that matches \texttt{<regexp>} and from server \texttt{<server>}. Example:
|
|
\begin{verbatim}
|
|
{acl, tests, {user, "^test", "localhost"}}.
|
|
\end{verbatim}
|
|
\item[\texttt{\{server\_regexp, <regexp>\}}] Matches any JID from server that
|
|
matches \texttt{<regexp>}. Example:
|
|
\begin{verbatim}
|
|
{acl, icq, {server, "^icq\\."}}.
|
|
\end{verbatim}
|
|
\item[\texttt{\{node\_regexp, <user\_regexp>, <server\_regexp>\}}] Matches user
|
|
with name that matches \texttt{<user\_regexp>} and from server that matches
|
|
\texttt{<server\_regexp>}. Example:
|
|
\begin{verbatim}
|
|
{acl, aleksey, {node_regexp, "^aleksey", "^jabber.(ru|org)$"}}.
|
|
\end{verbatim}
|
|
%$
|
|
\item[\texttt{\{user\_glob, <glob>\}}]
|
|
\item[\texttt{\{user\_glob, <glob>, <server>\}}]
|
|
\item[\texttt{\{server\_glob, <glob>\}}]
|
|
\item[\texttt{\{node\_glob, <user\_glob>, <server\_glob>\}}] This is same as
|
|
above, but uses shell glob patterns instead of regexp. These patterns can
|
|
have following special characters:
|
|
\begin{description}
|
|
\item[\texttt{*}] matches any string including the null string.
|
|
\item[\texttt{?}] matches any single character.
|
|
\item[\texttt{[\ldots{}]}] matches any of the enclosed characters. Character
|
|
ranges are specified by a pair of characters separated by a \texttt{`-'}.
|
|
If the first character after \texttt{`['} is a \texttt{`!'}, then any
|
|
character not enclosed is matched.
|
|
\end{description}
|
|
\end{description}
|
|
|
|
The following ACLs pre-defined:
|
|
\begin{description}
|
|
\item[\texttt{all}] Matches all JIDs.
|
|
\item[\texttt{none}] Matches none JIDs.
|
|
\end{description}
|
|
|
|
An entry allowing or denying different services would look similar to this:
|
|
\begin{verbatim}
|
|
{access, <accessname>, [{allow, <aclname>},
|
|
{deny, <aclname>},
|
|
...
|
|
]}.
|
|
\end{verbatim}
|
|
When a JID is checked to have access to \texttt{<accessname>}, 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 ``\texttt{deny}'' is returned.
|
|
|
|
Example:
|
|
\begin{verbatim}
|
|
{access, configure, [{allow, admin}]}.
|
|
{access, something, [{deny, badmans},
|
|
{allow, all}]}.
|
|
\end{verbatim}
|
|
|
|
Following access rules pre-defined:
|
|
\begin{description}
|
|
\item[\texttt{all}] Always return ``\texttt{allow}''
|
|
\item[\texttt{none}] Always return ``\texttt{deny}''
|
|
\end{description}
|
|
|
|
|
|
|
|
\subsubsection{Shapers Configuration}
|
|
\label{sec:configshaper}
|
|
|
|
With shapers is possible to bound connection traffic. The declarations of
|
|
shapers in config file have following syntax:
|
|
\begin{verbatim}
|
|
{shaper, <shapername>, <kind>}.
|
|
\end{verbatim}
|
|
Currently implemented only one kind of shaper: \texttt{maxrate}. It have
|
|
following syntax:
|
|
\begin{verbatim}
|
|
{maxrate, <rate>}
|
|
\end{verbatim}
|
|
where \texttt{<rate>} means maximum allowed incomig rate in bytes/second.
|
|
E.\,g.\ to define shaper with name ``\texttt{normal}'' and maximum allowed rate
|
|
1000\,bytes/s, add following line in config:
|
|
\begin{verbatim}
|
|
{shaper, normal, {maxrate, 1000}}.
|
|
\end{verbatim}
|
|
|
|
|
|
|
|
|
|
\subsubsection{Listened Sockets}
|
|
\label{sec:configlistened}
|
|
|
|
Option \texttt{listen} defines list of listened sockets and what services
|
|
runned on them. Each element of list is a tuple with following elements:
|
|
\begin{itemize}
|
|
\item Port number;
|
|
\item Module that serves this port;
|
|
\item Options to this module.
|
|
\end{itemize}
|
|
|
|
Currently three modules are implemented:
|
|
\begin{description}
|
|
\item[\verb|ejabberd_c2s|] This module serves C2S connections.
|
|
|
|
The following options are defined:
|
|
\begin{description}
|
|
\item[\verb|{access, <access rule>}|] This option defines access of users
|
|
to this C2S port. Default value is ``\texttt{all}''.
|
|
\item[\verb|{shaper, <access rule>}|] This option is like previous, but
|
|
use shapers instead of ``\texttt{allow}'' and ``\texttt{deny}''. Default
|
|
value is ``\texttt{none}''.
|
|
\item[\verb|{ssl, SSLOpts}|] This option defines that traffic on this port
|
|
will be encrypted using SSL. SSL options are the same as described by
|
|
``\verb|erl -man ssl|'' command
|
|
\end{description}
|
|
\item[\verb|ejabberd_s2s_in|] This module serves incoming S2S connections.
|
|
\item[\verb|ejabberd_service|] This module serves connections from \Jabber{}
|
|
services (i.\,e.\ that use the \texttt{jabber:component:accept} namespace).
|
|
\end{description}
|
|
|
|
For example, the following configuration defines that C2S connections are
|
|
listened on port 5222 and 5223 (SSL) and denied for user ``\texttt{bad}'', S2S
|
|
on port 5269, and that service \texttt{conference.example.org} must be
|
|
connected to port 8888 with a password ``\texttt{secret}''. Also all users
|
|
except admins have traffic limit 1000\,b/s.
|
|
\begin{verbatim}
|
|
{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, []},
|
|
{8888, ejabberd_service,
|
|
[{host, "conference.example.org", [{password, "secret"}]}]}
|
|
]}.
|
|
\end{verbatim}
|
|
|
|
|
|
|
|
|
|
\subsubsection{Modules}
|
|
\label{sec:configmodules}
|
|
|
|
Option \texttt{modules} defines the list of modules that will be loaded after
|
|
\ejabberd{} 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~\ref{sec:modules} for detailed information on each module.
|
|
|
|
Example:
|
|
\begin{verbatim}
|
|
{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, []}
|
|
]}.
|
|
\end{verbatim}
|
|
|
|
|
|
\subsection{Online Configuration and Monitoring}
|
|
\label{sec:onlineconfig}
|
|
|
|
To perform online reconfiguration of \ejabberd{} you will need to have
|
|
\modconfigure{} loaded (see section~\ref{sec:modconfigure}). It is also highly
|
|
recommended to load \moddisco{} as well (see section~\ref{sec:moddisco}),
|
|
because \modconfigure{} is highly integrated with it. Additionally it is
|
|
recommended to use a disco- and xdata-capable client such as
|
|
\footahref{http://www.jabber.ru/projects/tkabber/index\_en.html}{Tkabber}
|
|
(which was developed synchronously with \ejabberd{}, its CVS version
|
|
supports most of \ejabberd{} features).
|
|
|
|
|
|
|
|
|
|
On disco query \ejabberd{} returns following items:
|
|
\begin{itemize}
|
|
\item Identity of server.
|
|
\item List of features, including defined namespaces.
|
|
\item List of JIDs from route table.
|
|
\item List of disco-nodes described in following subsections.
|
|
\end{itemize}
|
|
\begin{figure}[htbp]
|
|
\centering
|
|
\insimg{disco.png}
|
|
\caption{Tkabber Discovery window}
|
|
\label{fig:disco}
|
|
\end{figure}
|
|
|
|
\subsubsection{Node \texttt{config}: Global Configuration}
|
|
|
|
Under this node the following nodes exists:
|
|
|
|
\paragraph{Node \texttt{config/hostname}}
|
|
|
|
Via \ns{jabber:x:data} queries to this node possible to change host name of
|
|
this \ejabberd{} server. (See figure~\ref{fig:hostname}) (Currently this works
|
|
correctly only after a restart)
|
|
\begin{figure}[htbp]
|
|
\centering
|
|
\insimg{confhostname.png}
|
|
\caption{Editing of hostname}
|
|
\label{fig:hostname}
|
|
\end{figure}
|
|
|
|
|
|
\paragraph{Node \texttt{config/acls}}
|
|
|
|
Via \ns{jabber:x:data} queries to this node it is possible to edit ACLs list.
|
|
(See figure~\ref{fig:acls})
|
|
\begin{figure}[htbp]
|
|
\centering
|
|
\insimg{confacls.png}
|
|
\caption{Editing of ACLs}
|
|
\label{fig:acls}
|
|
\end{figure}
|
|
|
|
|
|
\paragraph{Node \texttt{config/access}}
|
|
|
|
Via \ns{jabber:x:data} queries to this node it is possible to edit access
|
|
rules.
|
|
|
|
|
|
\paragraph{Node \texttt{config/remusers}}
|
|
|
|
Via \ns{jabber:x:data} 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).
|
|
|
|
|
|
|
|
|
|
\subsubsection{Node \texttt{online users}: List of Online Users}
|
|
|
|
|
|
|
|
|
|
\subsubsection{Node \texttt{all users}: List of Registered Users}
|
|
|
|
\begin{figure}[htbp]
|
|
\centering
|
|
\insimg{discoallusers.png}
|
|
\caption{Discovery all users}
|
|
\label{fig:discoallusers}
|
|
\end{figure}
|
|
|
|
|
|
\subsubsection{Node \texttt{outgoing s2s}: List of Outgoing S2S connections}
|
|
|
|
\subsubsection{Node \texttt{running nodes}: List of Running \ejabberd{} Nodes}
|
|
|
|
\begin{figure}[htbp]
|
|
\centering
|
|
\insimg{discorunnodes.png}
|
|
\caption{Discovery running nodes}
|
|
\label{fig:discorunnodes}
|
|
\end{figure}
|
|
|
|
\subsubsection{Node \texttt{stopped nodes}: List of Stopped Nodes}
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
TBD
|
|
|
|
\section{Distribution}
|
|
\label{sec:distribution}
|
|
|
|
|
|
\subsection{How it works}
|
|
\label{sec:howitworks}
|
|
|
|
|
|
|
|
A \Jabber{} domain is served by one or more \ejabberd{} 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
|
|
\texttt{\~{}ejabberd/.erlang.cookie} must be the same on all nodes). This is
|
|
needed because all nodes exchange information about connected users, S2S
|
|
connections, registered services, etc\ldots
|
|
|
|
|
|
|
|
Each \ejabberd{} node have following modules:
|
|
\begin{itemize}
|
|
\item router;
|
|
\item local router.
|
|
\item session manager;
|
|
\item S2S manager;
|
|
\end{itemize}
|
|
|
|
|
|
\subsubsection{Router}
|
|
|
|
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 \ejabberd{} node or
|
|
process. If it does not exists in either tables, then it sent to the S2S
|
|
manager.
|
|
|
|
|
|
\subsubsection{Local Router}
|
|
|
|
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.
|
|
|
|
|
|
\subsubsection{Session Manager}
|
|
|
|
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.
|
|
|
|
|
|
\subsubsection{S2S Manager}
|
|
|
|
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.
|
|
|
|
|
|
|
|
\appendix{}
|
|
|
|
\section{Built-in Modules}
|
|
\label{sec:modules}
|
|
|
|
\subsection{Common Options}
|
|
\label{sec:modcommonopts}
|
|
|
|
The following options are used by many modules, so they are described in
|
|
separate section.
|
|
|
|
\subsubsection{Option \texttt{iqdisc}}
|
|
|
|
Many modules define handlers for processing IQ queries of different namespaces
|
|
to this server or to user (e.\,g.\ to \texttt{example.org} or to
|
|
\texttt{user@example.org}). This option defines processing discipline of
|
|
these queries. Possible values are:
|
|
\begin{description}
|
|
\item[\texttt{no\_queue}] 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.
|
|
\item[\texttt{one\_queue}] 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.
|
|
\item[\texttt{parallel}] 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).
|
|
\end{description}
|
|
|
|
Example:
|
|
\begin{verbatim}
|
|
{modules, [
|
|
...
|
|
{mod_time, [{iqdisc, no_queue}]},
|
|
...
|
|
]}.
|
|
\end{verbatim}
|
|
|
|
|
|
\subsubsection{Option \texttt{host}}
|
|
|
|
Some modules may act as services, and wants to have different domain name.
|
|
This option explicitly defines this name.
|
|
|
|
Example:
|
|
\begin{verbatim}
|
|
{modules, [
|
|
...
|
|
{mod_echo, [{host, "echo.example.org"}]},
|
|
...
|
|
]}.
|
|
\end{verbatim}
|
|
|
|
|
|
|
|
\subsection{\modregister{}}
|
|
\label{sec:modregister}
|
|
|
|
This module adds support for
|
|
\footahref{http://www.jabber.org/jeps/jep-0077.html}{JEP-0077} (In-Band
|
|
Registration). There is possible to restrict registration via ``register''
|
|
access rule. If this rule returns ``deny'' on requested user name, then
|
|
registration is not allowed for it.
|
|
|
|
Options:
|
|
\begin{description}
|
|
\item[\texttt{iqdisc}] \ns{jabber:iq:register} IQ queries processing
|
|
discipline.
|
|
\end{description}
|
|
|
|
Example:
|
|
\begin{verbatim}
|
|
% 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, []},
|
|
...
|
|
]}.
|
|
\end{verbatim}
|
|
|
|
|
|
|
|
|
|
\subsection{\modroster{}}
|
|
\label{sec:modroster}
|
|
|
|
|
|
|
|
\subsection{\modconfigure{}}
|
|
\label{sec:modconfigure}
|
|
|
|
|
|
|
|
\subsection{\moddisco{}}
|
|
\label{sec:moddisco}
|
|
|
|
This module adds support for
|
|
\footahref{http://www.jabber.org/jeps/jep-0030.html}{JEP-0030} (Service
|
|
Discovery).
|
|
|
|
Options:
|
|
\begin{description}
|
|
\item[\texttt{iqdisc}] \ns{http://jabber.org/protocol/disco#items} and
|
|
\ns{http://jabber.org/protocol/disco#info} IQ queries processing discipline.
|
|
\item[\texttt{extra\_domains}] List of domains that will be added to server
|
|
items reply
|
|
\end{description}
|
|
|
|
Example:
|
|
\begin{verbatim}
|
|
{modules, [
|
|
...
|
|
{mod_disco, [[{extra_domains, ["jit.example.com",
|
|
"etc.example.com"]}]]},
|
|
...
|
|
]}.
|
|
\end{verbatim}
|
|
|
|
|
|
\subsection{\modstats{}}
|
|
\label{sec:modstats}
|
|
|
|
This module adds support for
|
|
\footahref{http://www.jabber.org/jeps/jep-0039.html}{JEP-0039} (Statistics
|
|
Gathering).
|
|
|
|
Options:
|
|
\begin{description}
|
|
\item[\texttt{iqdisc}] \ns{http://jabber.org/protocol/stats} IQ queries
|
|
processing discipline.
|
|
\end{description}
|
|
|
|
TBD about access.
|
|
|
|
\subsection{\modvcard{}}
|
|
\label{sec:modvcard}
|
|
|
|
|
|
|
|
\subsection{\modoffline{}}
|
|
\label{sec:modoffline}
|
|
|
|
|
|
|
|
\subsection{\modecho{}}
|
|
\label{sec:modecho}
|
|
|
|
|
|
|
|
\subsection{\modprivate{}}
|
|
\label{sec:modprivate}
|
|
|
|
This module adds support of
|
|
\footahref{http://www.jabber.org/jeps/jep-0049.html}{JEP-0049} (Private XML
|
|
Storage).
|
|
|
|
Options:
|
|
\begin{description}
|
|
\item[\texttt{iqdisc}] \ns{jabber:iq:private} IQ queries processing discipline.
|
|
\end{description}
|
|
|
|
\subsection{\modtime{}}
|
|
\label{sec:modtime}
|
|
|
|
This module answers UTC time on \ns{jabber:iq:time} queries.
|
|
|
|
Options:
|
|
\begin{description}
|
|
\item[\texttt{iqdisc}] \ns{jabber:iq:time} IQ queries processing discipline.
|
|
\end{description}
|
|
|
|
|
|
\subsection{\modversion{}}
|
|
\label{sec:modversion}
|
|
|
|
This module answers \ejabberd{} version on \ns{jabber:iq:version} queries.
|
|
|
|
Options:
|
|
\begin{description}
|
|
\item[\texttt{iqdisc}] \ns{jabber:iq:version} IQ queries processing discipline.
|
|
\end{description}
|
|
|
|
|
|
|
|
|
|
\section{I18n/L10n}
|
|
\label{sec:i18nl10n}
|
|
|
|
Many modules supports \texttt{xml:lang} attribute inside IQ queries. E.\,g.\
|
|
on figure~\ref{fig:discorus} (compare it with figure~\ref{fig:disco}) showed
|
|
reply on following query:
|
|
\begin{verbatim}
|
|
<iq id='5'
|
|
to='e.localhost'
|
|
type='get'>
|
|
<query xmlns='http://jabber.org/protocol/disco#items'
|
|
xml:lang='ru'/>
|
|
</iq>
|
|
\end{verbatim}
|
|
|
|
\begin{figure}[htbp]
|
|
\centering
|
|
\insimg{discorus.png}
|
|
\caption{Discovery result when \texttt{xml:lang='ru'}}
|
|
\label{fig:discorus}
|
|
\end{figure}
|
|
|
|
|
|
\end{document}
|