xmpp.chapril.org-ejabberd/doc/guide.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}}

%\setcounter{tocdepth}{3}


\title{Ejabberd Installation and Operation Guide}
\author{Alexey Shchepin \\
  \ahrefurl{mailto:alexey@sevcom.net} \\
  \ahrefurl{xmpp:aleksey@jabber.ru}}
\date{February 11, 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 Distributed: You may run \ejabberd{} on a cluster of machines and all of
  them will serve one Jabber domain.
\item Fault-tolerance: You may setup an \ejabberd{} cluster so that all the
  information required for a properly working service will be stored
  permanently on more then 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 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.
\item JUD based on users vCards.
\end{itemize}




\section{Installation}
\label{sec:installation}


\subsection{Installation Requirements}
\label{sec:installreq}

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}

\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:cvs@www.jabber.ru:/var/spool/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}

\begin{verbatim}
./configure
make
\end{verbatim}

TBD



%\subsection{Initial Configuration}
%\label{sec:initconfig}


\subsection{Starting}
\label{sec:starting}

\ldots{} To use more then 1024 connections, you will need to set environment
variable \texttt{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)\ldots{}

\begin{verbatim}
erl -name ejabberd -s ejabberd
\end{verbatim}

TBD

\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 Function in this module that starts connection (likely will be removed);
\item Options to this module.
\end{itemize}

Currently three modules are implemented:
\begin{description}
\item[\texttt{ejabberd\_c2s}] This module serves C2S connections.
  
  Following options defined:
  \begin{description}
  \item[\texttt{\{access, <access rule>\}}] This option defines access of users
    to this C2S port.  Default value is ``\texttt{all}''.
  \item[\texttt{\{shaper, <access rule>\}}] This option is like previous, but
    use shapers instead of ``\texttt{allow}'' and ``\texttt{deny}''.  Default
    value is ``\texttt{none}''.
  \end{description}
\item[\texttt{ejabberd\_s2s\_in}] This module serves incoming S2S connections.
\item[\texttt{ejabberd\_service}] This module serves connections to \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 denied for user ``\texttt{bad}'', S2S on port 5269
and that service \texttt{conference.jabber.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,     start, [{access, c2s},
                                           {shaper, c2s_shaper}]},
          {5269, ejabberd_s2s_in,  start, []},
          {8888, ejabberd_service, start,
           [{host, "conference.jabber.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 User}

\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 must run 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 itdoes not exists in either table, 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 node, 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}

Following options used by many modules, so they 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{myjabber.org} or to
\texttt{user@myjabber.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
  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.
\item[\texttt{parallel}] 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.
\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.myjabber.org"}]},
           ...
          ]}.
\end{verbatim}



\subsection{\modregister{}}
\label{sec:modregister}



\subsection{\modroster{}}
\label{sec:modroster}



\subsection{\modconfigure{}}
\label{sec:modconfigure}



\subsection{\moddisco{}}
\label{sec:moddisco}



\subsection{\modstats{}}
\label{sec:modstats}

This module adds support of
\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 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}