\documentclass[10pt]{article}

\usepackage{graphics}
\usepackage{hevea}
\usepackage{verbatim}


\newcommand{\imgscale}{0.7}
\newcommand{\insimg}[1]{
  \imgsrc{#1}{}
  \begin{latexonly}
    \scalebox{\imgscale}{\includegraphics{#1}}
  \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}}



\title{Ejabberd Installation and Operation Guide}
\author{Alexey Shchepin \\
  \ahrefurl{mailto:alexey@sevcom.net} \\
  \ahrefurl{xmpp:aleksey@jabber.ru}}
\date{February 3, 2003}

\begin{document}
\begin{titlepage}
  \maketitle{}
  
  {\centering
    \insimg{logo.png}
    \par
  }
\end{titlepage}
%\newpage
\tableofcontents{}

\newpage
\section{Introduction}
\label{sec:intro}

\ejabberd{} is a Free and Open Source distributed fault-tolerant \Jabber{}
server.  It writen mostly in Erlang.

Main features of ejabberd is:
\begin{itemize}
\item Distribution.  You can run ejaberd on cluster of machines and all them
  will serve one Jabber domain.
\item   Fault-tolerance.  You can setup ejabberd cluster in such way, that all
  information required for properly working will be stored permanently on more
  then one machine, so if one of them crashed, then all other ones continue
  working without any pauses.  Also you can replace or add more machines ``on
  the fly''.
\item Support of \footahref{http://www.jabber.org/jeps/jep-0030.html}{JEP-0030}
  (Service Discovery).
\item Support of \footahref{http://www.jabber.org/jeps/jep-0039.html}{JEP-0039}
  (Statistics Gathering).
\item Support of \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 need 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 released.

Latest alpha version can be retrieved via CVS\@.  Do following steps:
\begin{itemize}
\item \texttt{export CVSROOT=:pserver:cvs@www.jabber.ru:/var/spool/cvs}
\item \texttt{cvs login}
\item Enter empty 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}

\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}

Configuration file is loaded after first start of \ejabberd{}.  It consists of
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.  Note, that after first start all values from this file stored in
database, and in next time they will be APPENDED to existing values.  E.\,g.\
if this file will not contain ``host'' definition, then old value will be
used.

To override old values 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 done via Access Control Lists (ACL).
Declaration 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
  mathes \texttt{<regexp>}.  Example:
\begin{verbatim}
{acl, tests, {user, "test.*"}}.
\end{verbatim}

\item[\texttt{\{user\_regexp, <regexp>, <server>\}}] Matches user with name
  that mathes \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 mathes \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 use shell glob patterns instead of regexp.  This 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}

Following ACLs pre-defined:
\begin{description}
\item[\texttt{all}] Matches all JIDs.
\item[\texttt{none}] Matches none JIDs.
\end{description}

Allowing or denying of different services is like this:
\begin{verbatim}
{access, <accessname>, [{allow, <aclname>},
                        {deny, <aclname>},
                        ...
                       ]}.
\end{verbatim}
When JID is checked to have access to \texttt{<accessname>}, server
sequentially checks if this JID in one of the ACLs that are second elements in
each tuple in list.  If one of them matched, then returned first element of
matched tuple.  Else returned ``\texttt{deny}''.

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{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 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}''.
  \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 \texttt{jabber:component:accept} namespace).
\end{description}

For example, following configuration defines that C2S connections 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
password ``\texttt{secret}''.

\begin{verbatim}
{acl, blocked, {user, "bad"}}.
{access, c2s, [{deny, blocked},
               {allow, all}]}.
{listen, [{5222, ejabberd_c2s,     start, [{access, c2s}]},
          {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 list of modules that will be loaded after
\ejabberd{} 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~\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 use facility of online reconfiguration of \ejabberd{} needed to have
\modconfigure{} loaded (see section~\ref{sec:modconfigure}).  Also highly
recommended to load \moddisco{} (see section~\ref{sec:moddisco}), because
\modconfigure{} highly integrates with it.  Also recommended to use disco- and
xdata-capable client
(\footahref{http://www.jabber.ru/projects/tkabber/index\_en.html}{Tkabber}
developed synchronously with \ejabberd{}, its CVS version use 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}


\subsubsection{Node \texttt{config}: Global Configuration}

Under this node exists following nodes:

\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 will work
correctly only after restart)
\begin{figure}[htbp]
  \centering
  [hostname editing window]
  \caption{Editing of hostname}
  \label{fig:hostname}
\end{figure}


\paragraph{Node \texttt{config/acls}}

Via \ns{jabber:x:data} queries to this node possible edit ACLs list.  (See
figure~\ref{fig:acls})
\begin{figure}[htbp]
  \centering
  [acls editing window]
  \caption{Editing of ACLs}
  \label{fig:acls}
\end{figure}


\paragraph{Node \texttt{config/access}}

Via \ns{jabber:x:data} queries to this node possible edit access rules.
\textbf{Not work yet}.

\paragraph{Node \texttt{config/remusers}}

Via \ns{jabber:x:data} queries to this node 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 Connected User}

\subsubsection{Node \texttt{outgoing s2s}: List of Outgoing S2S connections}

\subsubsection{Node \texttt{running nodes}: List of Running \ejabberd{} Nodes}

\subsubsection{Node \texttt{stopped nodes}: List of Stopped Nodes}







TBD

\section{Distribution}
\label{sec:distribution}


\subsection{How it works}
\label{sec:howitworks}

\Jabber{} domain is served by one or more \ejabberd{} 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
\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 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 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 \ejabberd{} node or process.  If it not
exists in both tables, then it sended to S2S manager.


\subsubsection{Local Router}

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.


\subsubsection{Session Manager}

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.


\subsubsection{S2S Manager}

This module route packets to another \Jabber{} servers.  First, it check if
already exists opened S2S connection from domain of packet source to domain of
destination.  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.


\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 this
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}






\end{document}
