1194 lines
36 KiB
TeX
1194 lines
36 KiB
TeX
\documentclass[a4paper,10pt]{article}
|
|
|
|
\usepackage{graphics}
|
|
\usepackage{hevea}
|
|
\usepackage{verbatim}
|
|
|
|
\usepackage[twosideshift=0pt]{geometry}
|
|
|
|
\usepackage[pdftex,colorlinks,unicode,urlcolor=blue,linkcolor=blue,pdftitle=Ejabberd\
|
|
Installation\ and\ Operation\ Guide,pdfauthor=Alexey\
|
|
Shchepin,pdfsubject=ejabberd,pdfkeywords=ejabberd]{hyperref}
|
|
|
|
\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{\bracehack}{\def\{{\char"7B}\def\}{\char"7D}}
|
|
|
|
\newcommand{\ns}[1]{\texttt{#1}}
|
|
\newcommand{\jid}[1]{\texttt{#1}}
|
|
\newcommand{\option}[1]{\texttt{#1}}
|
|
\newcommand{\poption}[1]{{\bracehack\texttt{#1}}}
|
|
\newcommand{\node}[1]{\texttt{#1}}
|
|
\newcommand{\term}[1]{\texttt{#1}}
|
|
\newcommand{\shell}[1]{\texttt{#1}}
|
|
\newcommand{\ejabberd}{\texttt{ejabberd}}
|
|
\newcommand{\Jabber}{Jabber}
|
|
|
|
\newcommand{\module}[1]{\texttt{#1}}
|
|
\newcommand{\modannounce}{\module{mod\_announce}}
|
|
\newcommand{\modconfigure}{\module{mod\_configure}}
|
|
\newcommand{\moddisco}{\module{mod\_disco}}
|
|
\newcommand{\modirc}{\module{mod\_irc}}
|
|
\newcommand{\modlast}{\module{mod\_last}}
|
|
\newcommand{\modmuc}{\module{mod\_muc}}
|
|
\newcommand{\modecho}{\module{mod\_echo}}
|
|
\newcommand{\modoffline}{\module{mod\_offline}}
|
|
\newcommand{\modprivacy}{\module{mod\_privacy}}
|
|
\newcommand{\modprivate}{\module{mod\_private}}
|
|
\newcommand{\modpubsub}{\module{mod\_pubsub}}
|
|
\newcommand{\modregister}{\module{mod\_register}}
|
|
\newcommand{\modroster}{\module{mod\_roster}}
|
|
\newcommand{\modservicelog}{\module{mod\_service\_log}}
|
|
\newcommand{\modstats}{\module{mod\_stats}}
|
|
\newcommand{\modtime}{\module{mod\_time}}
|
|
\newcommand{\modvcard}{\module{mod\_vcard}}
|
|
\newcommand{\modversion}{\module{mod\_version}}
|
|
|
|
\newcommand{\titem}[1]{\item[\bracehack\texttt{#1}]}
|
|
|
|
%\setcounter{tocdepth}{3}
|
|
\begin{latexonly}
|
|
\global\parskip=9pt plus 3pt minus 1pt
|
|
\global\parindent=0pt
|
|
|
|
\gdef\ahrefurl#1{\href{#1}{\texttt{#1}}}
|
|
\gdef\footahref#1#2{#2\footnote{\href{#1}{\texttt{#1}}}}
|
|
\end{latexonly}
|
|
|
|
\newcommand{\tjepref}[2]{\footahref{http://www.jabber.org/jeps/jep-#1.html}{#2}}
|
|
\newcommand{\jepref}[1]{\tjepref{#1}{JEP-#1}}
|
|
|
|
\newcommand{\iqdiscitem}[1]{\titem{iqdisc} #1 IQ queries processing
|
|
discipline (see~\ref{sec:modiqdiscoption}).}
|
|
\newcommand{\hostitem}[1]{\titem{host} Defines hostname of service
|
|
(see~\ref{sec:modhostoption}). If not present
|
|
then prefix \jid{#1.} is added to main \ejabberd{} hostname.}
|
|
|
|
\title{Ejabberd Installation and Operation Guide}
|
|
\author{Alexey Shchepin \\
|
|
\ahrefurl{mailto:alexey@sevcom.net} \\
|
|
\ahrefurl{xmpp:aleksey@jabber.ru}}
|
|
\date{June 24, 2004}
|
|
|
|
\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 written mostly in Erlang.
|
|
|
|
The main features of \ejabberd{} are:
|
|
\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 to let all of
|
|
them 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 nodes ``on the fly''.
|
|
\item Built-in \tjepref{0045}{Multi-User Chat} service
|
|
\item Built-in IRC transport
|
|
\item Built-in \tjepref{0060}{Publish-Subscribe} service
|
|
\item Built-in Jabber Users Directory service based on users vCards
|
|
\item Built-in web-based administration interface
|
|
\item Built-in \tjepref{0025}{HTTP Polling} service
|
|
\item SSL support
|
|
\item Support for LDAP authentification
|
|
\item Ability to interface with external components (JIT, MSN-t, Yahoo-t, etc.)
|
|
\item Migration from jabberd14 is possible
|
|
\item Mostly XMPP-compliant
|
|
\item Support for \jepref{0030} (Service Discovery).
|
|
\item Support for \jepref{0039} (Statistics Gathering).
|
|
\item Support for \ns{xml:lang}
|
|
\end{itemize}
|
|
|
|
The misfeatures of \ejabberd{} are:
|
|
\begin{itemize}
|
|
\item No support for virtual domains
|
|
\item No support for authentification and STARTTLS in S2S connections
|
|
\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;
|
|
\item OpenSSL 0.9.6 or later (optional).
|
|
\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\_R9C-0.exe}{Erlang/OTP R9C-0}
|
|
\item \footahref{http://prdownloads.sourceforge.net/expat/expat\_win32bin\_1\_95\_7.exe?download}{Expat 1.95.7}
|
|
\item
|
|
\footahref{http://ftp.gnu.org/pub/gnu/libiconv/libiconv-1.9.1.tar.gz}{Iconv 1.9.1}
|
|
(optional)
|
|
\item \footahref{http://www.slproweb.com/products/Win32OpenSSL.html}{Shining Light OpenSSL}
|
|
(to enable SSL connections)
|
|
\end{itemize}
|
|
|
|
|
|
\subsection{Obtaining}
|
|
\label{sec:obtaining}
|
|
|
|
Stable \ejabberd{} release can be obtained at
|
|
\ahrefurl{http://www.jabberstudio.org/projects/ejabberd/releases/}.
|
|
|
|
The latest alpha version can be retrieved from CVS\@.
|
|
\begin{verbatim}
|
|
export CVSROOT=:pserver:anonymous@jabberstudio.org:/home/cvs
|
|
cvs login
|
|
<press Enter when asked for a password>
|
|
cvs -z3 co ejabberd
|
|
\end{verbatim}
|
|
|
|
|
|
\subsection{Compilation}
|
|
\label{sec:compilation}
|
|
\subsubsection{Unix}
|
|
\label{sec:compilationunix}
|
|
|
|
\begin{verbatim}
|
|
./configure
|
|
make
|
|
su
|
|
make install
|
|
\end{verbatim}
|
|
|
|
This will install \ejabberd{} to \verb|/var/lib/ejabberd| directory,
|
|
\verb|ejabberd.cfg| to \verb|/etc/ejabberd| directory and create
|
|
\verb|/var/log/ejabberd| directory for log files.
|
|
|
|
\subsubsection{Windows}
|
|
\label{sec:compilationwin}
|
|
|
|
\begin{itemize}
|
|
\item Install Erlang emulator (for example, into \verb|C:\Program Files\erl5.3|).
|
|
\item Install Expat library into \verb|C:\Program Files\Expat-1.95.7|
|
|
directory.
|
|
|
|
Copy file \verb|C:\Program Files\Expat-1.95.7\Libs\libexpat.dll|
|
|
to your Windows system directory (for example, \verb|C:\WINNT| or
|
|
\verb|C:\WINNT\System32|)
|
|
\item Build and install Iconv library into \verb|C:\Program Files\iconv-1.9.1| directory.
|
|
|
|
Copy file \verb|C:\Program Files\iconv-1.9.1\bin\iconv.dll| to your
|
|
Windows system directory.
|
|
|
|
Note: Instead of copying libexpat.dll and iconv.dll to Windows
|
|
directory, you can add directories
|
|
\verb|C:\Program Files\Expat-1.95.7\Libs| and
|
|
\verb|C:\Program Files\iconv-1.9.1\bin| to \verb|PATH| environment
|
|
variable.
|
|
\item Being in \verb|ejabberd\src| directory run:
|
|
\begin{verbatim}
|
|
configure.bat
|
|
nmake -f Makefile.win32
|
|
\end{verbatim}
|
|
\item Edit file \verb|ejabberd\src\ejabberd.cfg| and run
|
|
\begin{verbatim}
|
|
werl -s ejabberd -name ejabberd
|
|
\end{verbatim}
|
|
\end{itemize}
|
|
|
|
%\subsection{Initial Configuration}
|
|
%\label{sec:initconfig}
|
|
|
|
|
|
\subsection{Starting}
|
|
\label{sec:starting}
|
|
|
|
To start \ejabberd{}, use the following command:
|
|
\begin{verbatim}
|
|
erl -pa /var/lib/ejabberd/ebin -name ejabberd -s ejabberd
|
|
\end{verbatim}
|
|
or
|
|
\begin{verbatim}
|
|
erl -pa /var/lib/ejabberd/ebin -sname ejabberd -s ejabberd
|
|
\end{verbatim}
|
|
In the latter case Erlang node will be identified using only first part of host
|
|
name, i.\,e. other Erlang nodes outside this domain can't contact this node.
|
|
|
|
Note that when using above command \ejabberd{} will search for config file
|
|
in current directory and will use current directory for storing user database
|
|
and logging.
|
|
|
|
To specify path to config file, log files and Mnesia database directory,
|
|
you may use the following command:
|
|
\begin{verbatim}
|
|
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\"
|
|
\end{verbatim}
|
|
|
|
You can find other useful options in Erlang manual page (\shell{erl -man erl}).
|
|
|
|
To use more than 1024 connections, you should 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 may 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}
|
|
|
|
The configuration file is initially loaded the first time \ejabberd{} 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 \term{`\%'} 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 \option{hostname} defines name of \Jabber{} domain that \ejabberd{}
|
|
serves. E.\,g.\ to use \jid{jabber.org} domain add the following line in the config:
|
|
\begin{verbatim}
|
|
{host, "jabber.org"}.
|
|
\end{verbatim}
|
|
|
|
%This option is mandatory.
|
|
|
|
\subsubsection{Default Language}
|
|
\label{sec:configlanguage}
|
|
|
|
Option \option{language} defines default language of \ejabberd{} messages, sent
|
|
to users. Default value is \term{"en"}. In order to take effect there must be a
|
|
translation file \term{<language>.msg} in \ejabberd{} \term{msgs} directory.
|
|
E.\,g.\ to use Russian as default language add the following line in the config:
|
|
\begin{verbatim}
|
|
{language, "ru"}.
|
|
\end{verbatim}
|
|
|
|
|
|
\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}
|
|
|
|
\term{<acltype>} can be one of following:
|
|
\begin{description}
|
|
\titem{all} Matches all JIDs. Example:
|
|
\begin{verbatim}
|
|
{acl, all, all}.
|
|
\end{verbatim}
|
|
\titem{\{user, <username>\}} Matches local user with name
|
|
\term{<username>}. Example:
|
|
\begin{verbatim}
|
|
{acl, admin, {user, "aleksey"}}.
|
|
\end{verbatim}
|
|
\titem{\{user, <username>, <server>\}} Matches user with JID
|
|
\term{<username>@<server>} and any resource. Example:
|
|
\begin{verbatim}
|
|
{acl, admin, {user, "aleksey", "jabber.ru"}}.
|
|
\end{verbatim}
|
|
\titem{\{server, <server>\}} Matches any JID from server
|
|
\term{<server>}. Example:
|
|
\begin{verbatim}
|
|
{acl, jabberorg, {server, "jabber.org"}}.
|
|
\end{verbatim}
|
|
\titem{\{user\_regexp, <regexp>\}} Matches local user with name that
|
|
matches \term{<regexp>}. Example:
|
|
\begin{verbatim}
|
|
{acl, tests, {user, "^test[0-9]*$"}}.
|
|
\end{verbatim}
|
|
%$
|
|
\titem{\{user\_regexp, <regexp>, <server>\}} Matches user with name
|
|
that matches \term{<regexp>} and from server \term{<server>}. Example:
|
|
\begin{verbatim}
|
|
{acl, tests, {user, "^test", "localhost"}}.
|
|
\end{verbatim}
|
|
\titem{\{server\_regexp, <regexp>\}} Matches any JID from server that
|
|
matches \term{<regexp>}. Example:
|
|
\begin{verbatim}
|
|
{acl, icq, {server, "^icq\\."}}.
|
|
\end{verbatim}
|
|
\titem{\{node\_regexp, <user\_regexp>, <server\_regexp>\}} Matches user
|
|
with name that matches \term{<user\_regexp>} and from server that matches
|
|
\term{<server\_regexp>}. Example:
|
|
\begin{verbatim}
|
|
{acl, aleksey, {node_regexp, "^aleksey$", "^jabber.(ru|org)$"}}.
|
|
\end{verbatim}
|
|
\titem{\{user\_glob, <glob>\}}
|
|
\titem{\{user\_glob, <glob>, <server>\}}
|
|
\titem{\{server\_glob, <glob>\}}
|
|
\titem{\{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}
|
|
\titem{*} matches any string including the null string.
|
|
\titem{?} matches any single character.
|
|
\titem{[...]} matches any of the enclosed characters. Character
|
|
ranges are specified by a pair of characters separated by a \term{`-'}.
|
|
If the first character after \term{`['} is a \term{`!'}, then any
|
|
character not enclosed is matched.
|
|
\end{description}
|
|
\end{description}
|
|
|
|
The following ACLs pre-defined:
|
|
\begin{description}
|
|
\titem{all} Matches all JIDs.
|
|
\titem{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 \term{<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 ``\term{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}
|
|
\titem{all} Always return ``\term{allow}''
|
|
\titem{none} Always return ``\term{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: \term{maxrate}. It have
|
|
following syntax:
|
|
\begin{verbatim}
|
|
{maxrate, <rate>}
|
|
\end{verbatim}
|
|
where \term{<rate>} means maximum allowed incomig rate in bytes/second.
|
|
E.\,g.\ to define shaper with name ``\term{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 \option{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 these modules are implemented:
|
|
\begin{description}
|
|
\titem{ejabberd\_c2s} This module serves C2S connections.
|
|
|
|
The following options are defined:
|
|
\begin{description}
|
|
\titem{\{access, <access rule>\}} This option defines access of users
|
|
to this C2S port. Default value is ``\term{all}''.
|
|
\titem{\{shaper, <access rule>\}} This option is like previous, but
|
|
use shapers instead of ``\term{allow}'' and ``\term{deny}''. Default
|
|
value is ``\term{none}''.
|
|
\titem{\{ip, IPAddress\}} This option specifies which network interface to
|
|
listen on. For example \verb|{ip, {192, 168, 1, 1}}|.
|
|
\titem{inet6} Set up the socket for IPv6.
|
|
\titem{starttls} This option specifies that STARTTLS extension is available
|
|
on connections to this port. You should also set ``\verb|certfile|''
|
|
option.
|
|
\titem{tls} This option specifies that traffic on this port will be
|
|
encrypted using SSL immediately after connecting. You should also set
|
|
``\verb|certfile|'' option.
|
|
\titem{ssl} This option specifies that traffic on this port will be
|
|
encrypted using SSL. You should also set ``\verb|certfile|'' option. It
|
|
is recommended to use \term{tls} option instead.
|
|
\titem{\{certfile, Path\}} Path to a file containing the SSL certificate.
|
|
\end{description}
|
|
\titem{ejabberd\_s2s\_in} This module serves incoming S2S connections.
|
|
\titem{ejabberd\_service} This module serves connections from \Jabber{}
|
|
services (i.\,e.\ that use the \ns{jabber:component:accept} namespace).
|
|
|
|
The following additional options are defined for \term{ejabberd\_service}
|
|
(options \option{access}, \option{shaper}, \option{ip}, \option{inet6} are
|
|
still valid):
|
|
\begin{description}
|
|
\titem{\{host, Hostname, [HostOptions]\}} This option defines hostname of connected
|
|
service and allows to specify additional options, e.\,g.\
|
|
\poption{\{password, Secret\}}.
|
|
\titem{\{hosts, [Hostnames], [HostOptions]\}} The same as above, but allows to
|
|
specify several hostnames.
|
|
\end{description}
|
|
\titem{ejabberd\_http} This module serves incoming HTTP connections.
|
|
|
|
The following options are defined:
|
|
\begin{description}
|
|
\titem{http\_poll} This option enables \tjepref{0025}{HTTP Polling}
|
|
support. It is available then at \verb|http://server:port/http-poll/|.
|
|
|
|
\titem{web\_admin} This option enables web-based interface for \ejabberd{}
|
|
administration which is available at \verb|http://server:port/admin/|,
|
|
login and password should be equal to username and password of one of
|
|
registered users who have permission defined in ``configure'' access rule.
|
|
\end{description}
|
|
\end{description}
|
|
|
|
For example, the following configuration defines that:
|
|
\begin{itemize}
|
|
\item C2S connections are listened on port 5222 and 5223 (SSL) and denied for
|
|
user ``\term{bad}''
|
|
\item S2S connections are listened on port 5269
|
|
\item HTTP connections are listened on port 5280 and administration interface
|
|
and HTTP Polling support are enabled
|
|
\item All users except admins have traffic limit 1000\,B/s
|
|
\item AIM transport \jid{aim.example.org} is connected to port 5233 with
|
|
password ``\term{aimsecret}''
|
|
\item JIT transports \jid{icq.example.org} and \jid{sms.example.org} are
|
|
connected to port 5234 with password ``\term{jitsecret}''
|
|
\item MSN transport \jid{msn.example.org} is connected to port 5235 with
|
|
password ``\term{msnsecret}''
|
|
\item Yahoo! transport \jid{yahoo.example.org} is connected to port 5236 with
|
|
password ``\term{yahoosecret}''
|
|
\item Gadu-Gadu transport \jid{gg.example.org} is connected to port 5237 with
|
|
password ``\term{ggsecret}''
|
|
\item ILE service \jid{ile.example.org} is connected to port 5238 with
|
|
password ``\term{ilesecret}''
|
|
\end{itemize}
|
|
\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, []},
|
|
{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"}]}]}
|
|
]
|
|
}.
|
|
\end{verbatim}
|
|
Note, that for jabberd14- or wpjabberd-based services you have to make the
|
|
transports log and do XDB by themselves:
|
|
\begin{verbatim}
|
|
<!--
|
|
You have to add elogger and rlogger entries here when using ejabberd.
|
|
In this case the transport will do the logging.
|
|
-->
|
|
|
|
<log id='logger'>
|
|
<host/>
|
|
<logtype/>
|
|
<format>%d: [%t] (%h): %s</format>
|
|
<file>/var/log/jabber/service.log</file>
|
|
</log>
|
|
|
|
<!--
|
|
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.
|
|
-->
|
|
|
|
<xdb id="xdb">
|
|
<host/>
|
|
<load>
|
|
<!-- this is a lib of wpjabber or jabberd -->
|
|
<xdb_file>/usr/lib/jabber/xdb_file.so</xdb_file>
|
|
</load>
|
|
<xdb_file xmlns="jabber:config:xdb_file">
|
|
<spool><jabberd:cmdline flag='s'>/var/spool/jabber</jabberd:cmdline></spool>
|
|
</xdb_file>
|
|
</xdb>
|
|
\end{verbatim}
|
|
|
|
|
|
\subsubsection{Modules}
|
|
\label{sec:configmodules}
|
|
|
|
Option \term{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_privacy, []},
|
|
{mod_configure, []},
|
|
{mod_disco, []},
|
|
{mod_stats, []},
|
|
{mod_vcard, []},
|
|
{mod_offline, []},
|
|
{mod_echo, [{host, "echo.localhost"}]},
|
|
{mod_private, []},
|
|
{mod_irc, []},
|
|
{mod_muc, []},
|
|
{mod_pubsub, []},
|
|
{mod_time, [{iqdisc, no_queue}]},
|
|
{mod_last, []},
|
|
{mod_version, []}
|
|
]}.
|
|
\end{verbatim}
|
|
|
|
|
|
\subsection{Online Configuration and Monitoring}
|
|
\label{sec:onlineconfig}
|
|
|
|
\subsubsection{Web-based Administration Interface}
|
|
\label{sec:webadm}
|
|
|
|
To perform online reconfiguration of \ejabberd{} you need to enable
|
|
\term{ejabberd\_http} listener with option \term{web\_admin} (see
|
|
section~\ref{sec:configlistened}). After that you can open URL
|
|
\verb|http://server:port/admin/| with you favorite web-browser and enter
|
|
username and password of an \ejabberd{} user with administrator rights. E.\,g.
|
|
with such config:
|
|
\begin{verbatim}
|
|
...
|
|
{host, "example.org"}.
|
|
...
|
|
{listen,
|
|
[...
|
|
{5280, ejabberd_http, [web_admin]},
|
|
...
|
|
]
|
|
}.
|
|
\end{verbatim}
|
|
you should enter URL \verb|http://example.org:5280/admin/|. After
|
|
authentification you should see something like in figure~\ref{fig:webadmmain}.
|
|
\begin{figure}[htbp]
|
|
\centering
|
|
\insimg{webadmmain.png}
|
|
\caption{Web-administration top page}
|
|
\label{fig:webadmmain}
|
|
\end{figure}
|
|
Here you can edit access restrictions, manage users, create backup files,
|
|
manage DB, enable/disable listened ports, and view statistics.
|
|
|
|
|
|
\subsubsection{\term{ejabberdctl} tool}
|
|
\label{sec:ejabberdctl}
|
|
|
|
It is possible to do some administration operations using \term{ejabberdctl}
|
|
command-line tool. You can check available options running this command
|
|
without arguments:
|
|
\begin{verbatim}
|
|
% 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
|
|
\end{verbatim}
|
|
|
|
|
|
|
|
\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 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 \term{\~{}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 \option{iqdisc}}
|
|
\label{sec:modiqdiscoption}
|
|
|
|
Many modules define handlers for processing IQ queries of different namespaces
|
|
to this server or to user (e.\,g.\ to \jid{example.org} or to
|
|
\jid{user@example.org}). This option defines processing discipline of
|
|
these queries. Possible values are:
|
|
\begin{description}
|
|
\titem{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 relatively long time.
|
|
\titem{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.
|
|
\titem{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 \option{host}}
|
|
\label{sec:modhostoption}
|
|
|
|
This option explicitly defines hostname for the module which acts as a service.
|
|
|
|
Example:
|
|
\begin{verbatim}
|
|
{modules,
|
|
[
|
|
...
|
|
{mod_echo, [{host, "echo.example.org"}]},
|
|
...
|
|
]}.
|
|
\end{verbatim}
|
|
|
|
|
|
\subsection{\modannounce{}}
|
|
\label{sec:modannounce}
|
|
|
|
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 \jid{example.org}):
|
|
\begin{description}
|
|
\titem{example.org/announce/all} Message is sent to all registered users.
|
|
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).
|
|
\titem{example.org/announce/online} Message is sent to all connected users.
|
|
If the user is online and connected to several resources, all resources
|
|
will receive the message.
|
|
\titem{example.org/announce/motd} Message is set as MOTD (Message of the Day)
|
|
and will be sent to users as they login. In addition the message is sent to
|
|
all connected users (similar to \term{announce/online} resource).
|
|
\titem{example.org/announce/motd/update} Message is set as MOTD (Message of the Day)
|
|
and will be sent to users as they login. The message is \emph{not sent} to
|
|
all connected users.
|
|
\titem{example.org/announce/motd/delete} Any message sent to this JID
|
|
removes existing MOTD.
|
|
\end{description}
|
|
|
|
Options:
|
|
\begin{description}
|
|
\titem{access} Specifies who is allowed to send announce messages
|
|
and set MOTD (default value is \term{none}).
|
|
\end{description}
|
|
|
|
Example:
|
|
\begin{verbatim}
|
|
% Only admins can send announcement messages:
|
|
{access, announce, [{allow, admin}]}.
|
|
|
|
{modules,
|
|
[
|
|
...
|
|
{mod_announce, [{access, announce}]},
|
|
...
|
|
]}.
|
|
\end{verbatim}
|
|
|
|
|
|
\subsection{\modconfigure{}}
|
|
\label{sec:modconfigure}
|
|
|
|
Options:
|
|
\begin{description}
|
|
\iqdiscitem{\ns{ejabberd:config}}
|
|
\end{description}
|
|
|
|
|
|
\subsection{\moddisco{}}
|
|
\label{sec:moddisco}
|
|
|
|
This module adds support for \jepref{0030} (Service Discovery).
|
|
|
|
Options:
|
|
\begin{description}
|
|
\iqdiscitem{\ns{http://jabber.org/protocol/disco\#items} and
|
|
\ns{http://jabber.org/protocol/disco\#info}}
|
|
\titem{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{\modecho{}}
|
|
\label{sec:modecho}
|
|
|
|
This module acts as a service and simply returns to sender any \Jabber{} packet. Module may be
|
|
useful for debugging.
|
|
|
|
Options:
|
|
\begin{description}
|
|
\hostitem{echo}
|
|
\end{description}
|
|
|
|
|
|
\subsection{\modirc{}}
|
|
\label{sec:modirc}
|
|
|
|
This module implements IRC transport.
|
|
|
|
Options:
|
|
\begin{description}
|
|
\hostitem{irc}
|
|
\titem{access} Specifies who is allowed to use IRC transport (default value is \term{all}).
|
|
\end{description}
|
|
|
|
Example:
|
|
\begin{verbatim}
|
|
{modules,
|
|
[
|
|
...
|
|
{mod_irc, [{access, all}]},
|
|
...
|
|
]}.
|
|
\end{verbatim}
|
|
|
|
|
|
\subsection{\modlast{}}
|
|
\label{sec:modlast}
|
|
|
|
This module adds support for \jepref{0012} (Last Activity)
|
|
|
|
Options:
|
|
\begin{description}
|
|
\iqdiscitem{\ns{jabber:iq:last}}
|
|
\end{description}
|
|
|
|
|
|
\subsection{\modmuc{}}
|
|
\label{sec:modmuc}
|
|
|
|
This module implements \jepref{0045} (Multi-User Chat) service.
|
|
|
|
Options:
|
|
\begin{description}
|
|
\hostitem{conference}
|
|
\titem{access} Specifies who is allowed to use MUC service (default value is \term{all}).
|
|
\titem{access\_create} Specifies who is allowed to create new rooms at
|
|
MUC service (default value is \term{all}).
|
|
\titem{access\_admin} Specifies who is allowed to administrate MUC service
|
|
(default value is \term{none}, which means that only creator may administer her room).
|
|
\end{description}
|
|
|
|
Example:
|
|
\begin{verbatim}
|
|
% 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}]},
|
|
...
|
|
]}.
|
|
\end{verbatim}
|
|
|
|
|
|
\subsection{\modoffline{}}
|
|
\label{sec:modoffline}
|
|
|
|
This module implements offline message storage.
|
|
|
|
|
|
\subsection{\modprivacy{}}
|
|
\label{sec:modprivacy}
|
|
|
|
This module implements Privacy Rules as defined in XMPP IM
|
|
(see \ahrefurl{http://www.jabber.org/ietf/}).
|
|
|
|
Options:
|
|
\begin{description}
|
|
\iqdiscitem{\ns{jabber:iq:privacy}}
|
|
\end{description}
|
|
|
|
|
|
\subsection{\modprivate{}}
|
|
\label{sec:modprivate}
|
|
|
|
This module adds support of \jepref{0049} (Private XML Storage).
|
|
|
|
Options:
|
|
\begin{description}
|
|
\iqdiscitem{\ns{jabber:iq:private}}
|
|
\end{description}
|
|
|
|
|
|
\subsection{\modpubsub{}}
|
|
\label{sec:modpubsub}
|
|
|
|
This module implements \jepref{0060} (Publish-Subscribe Service).
|
|
|
|
Options:
|
|
\begin{description}
|
|
\hostitem{pubsub}
|
|
\titem{served\_hosts} Specifies which hosts are served by the service.
|
|
If absent then only main \ejabberd{} host is served.
|
|
\end{description}
|
|
|
|
Example:
|
|
\begin{verbatim}
|
|
{modules,
|
|
[
|
|
...
|
|
{mod_pubsub, [{served_hosts, ["example.com",
|
|
"example.org"]}]}
|
|
...
|
|
]}.
|
|
\end{verbatim}
|
|
|
|
|
|
\subsection{\modregister{}}
|
|
\label{sec:modregister}
|
|
|
|
This module adds support for \jepref{0077} (In-Band Registration).
|
|
|
|
Options:
|
|
\begin{description}
|
|
\titem{access} Specifies rule to restrict registration.
|
|
If this rule returns ``deny'' on requested user name, then
|
|
registration is not allowed for it. (default value is \term{all}, which means
|
|
no restrictions).
|
|
\iqdiscitem{\ns{jabber:iq:register}}
|
|
\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, [{access, register}]},
|
|
...
|
|
]}.
|
|
\end{verbatim}
|
|
|
|
|
|
\subsection{\modroster{}}
|
|
\label{sec:modroster}
|
|
|
|
This module implements roster management.
|
|
|
|
Options:
|
|
\begin{description}
|
|
\iqdiscitem{\ns{jabber:iq:roster}}
|
|
\end{description}
|
|
|
|
|
|
\subsection{\modservicelog{}}
|
|
\label{sec:modservicelog}
|
|
|
|
This module adds support for logging of user packets via any jabber service.
|
|
These packets encapsulated in <route/> element and sended to specified
|
|
services.
|
|
|
|
Options:
|
|
\begin{description}
|
|
\titem{loggers} Specifies a list of services which will receive users
|
|
packets.
|
|
\end{description}
|
|
|
|
Example:
|
|
\begin{verbatim}
|
|
{modules,
|
|
[
|
|
...
|
|
{mod_service_log, [{loggers, ["bandersnatch.example.com"]}]},
|
|
...
|
|
]}.
|
|
\end{verbatim}
|
|
|
|
|
|
\subsection{\modstats{}}
|
|
\label{sec:modstats}
|
|
|
|
This module adds support for \jepref{0039} (Statistics Gathering).
|
|
|
|
Options:
|
|
\begin{description}
|
|
\iqdiscitem{\ns{http://jabber.org/protocol/stats}}
|
|
\end{description}
|
|
|
|
TBD about access.
|
|
|
|
|
|
\subsection{\modtime{}}
|
|
\label{sec:modtime}
|
|
|
|
This module answers UTC time on \ns{jabber:iq:time} queries.
|
|
|
|
Options:
|
|
\begin{description}
|
|
\iqdiscitem{\ns{jabber:iq:time}}
|
|
\end{description}
|
|
|
|
|
|
\subsection{\modvcard{}}
|
|
\label{sec:modvcard}
|
|
|
|
This module implements simple Jabber User Directory (based on user vCards)
|
|
and answers server vCard on \ns{vcard-temp} queries.
|
|
|
|
Options:
|
|
\begin{description}
|
|
\hostitem{vjud}
|
|
\iqdiscitem{\ns{vcard-temp}}
|
|
\titem{search} Specifies wheather search is enabled (value is \term{true}, default) or
|
|
disabled (value is \term{false}) by the service. If \term{search} is set to \term{false},
|
|
option \term{host} is ignored and service does not appear in Jabber Discovery items.
|
|
\titem{matches} Limits the number of reported search results. If value is set to
|
|
\term{infinity} then all search results are reported. Default value is \term{30}.
|
|
\end{description}
|
|
|
|
Example:
|
|
\begin{verbatim}
|
|
{modules,
|
|
[
|
|
...
|
|
{mod_vcard, [{search, false}, {matches, 20}]}
|
|
...
|
|
]}.
|
|
\end{verbatim}
|
|
|
|
|
|
\subsection{\modversion{}}
|
|
\label{sec:modversion}
|
|
|
|
This module answers \ejabberd{} version on \ns{jabber:iq:version} queries.
|
|
|
|
Options:
|
|
\begin{description}
|
|
\iqdiscitem{\ns{jabber:iq:version}}
|
|
\end{description}
|
|
|
|
|
|
\section{I18n/L10n}
|
|
\label{sec:i18nl10n}
|
|
|
|
All built-in modules support \texttt{xml:lang} attribute inside IQ queries.
|
|
E.\,g.\ on figure~\ref{fig:discorus} showed the reply on the following query:
|
|
\begin{verbatim}
|
|
<iq id='5'
|
|
to='e.localhost'
|
|
type='get'
|
|
xml:lang='ru'>
|
|
<query xmlns='http://jabber.org/protocol/disco#items'/>
|
|
</iq>
|
|
\end{verbatim}
|
|
|
|
\begin{figure}[htbp]
|
|
\centering
|
|
\insimg{discorus.png}
|
|
\caption{Discovery result when \texttt{xml:lang='ru'}}
|
|
\label{fig:discorus}
|
|
\end{figure}
|
|
|
|
Also web-interface supports \verb|Accept-Language| HTTP header (see
|
|
figure~\ref{fig:webadmmainru}, compare it with figure~\ref{fig:webadmmain})
|
|
|
|
\begin{figure}[htbp]
|
|
\centering
|
|
\insimg{webadmmainru.png}
|
|
\caption{Web-administration top page with HTTP header
|
|
``\verb|Accept-Language: ru|''}
|
|
\label{fig:webadmmainru}
|
|
\end{figure}
|
|
|
|
|
|
\end{document}
|