diff --git a/ChangeLog b/ChangeLog index 156ee6fa5..84523cd3c 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,7 @@ +2006-09-22 Mickael Remond + + * doc/guide.tex: Large improvements (thanks to Sander Devrieze) + 2006-09-14 Mickael Remond * doc/guide.tex: Minor fix on index generation. diff --git a/doc/Makefile b/doc/Makefile index cc8b4d1b3..7736855f3 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -27,16 +27,13 @@ clean: rm -f *.toc guide.html: guide.tex - hevea guide.tex - hevea guide.tex - + hevea -fix -noiso -pedantic guide.tex + dev.html: dev.tex - hevea dev.tex - hevea dev.tex + hevea -fix -noiso -pedantic dev.tex features.html: features.tex - hevea features.tex - hevea features.tex + hevea -fix -noiso -pedantic features.tex guide.pdf: guide.tex pdflatex guide.tex diff --git a/doc/dev.html b/doc/dev.html index 8681b1521..6cb4d2a46 100644 --- a/doc/dev.html +++ b/doc/dev.html @@ -4,7 +4,7 @@ -Ejabberd 1.1.1 Developers Guide +Ejabberd 1.1.2 Developers Guide @@ -22,7 +22,7 @@ BLOCKQUOTE{margin-left:4ex;margin-right:4ex;text-align:left;} - + @@ -34,7 +34,7 @@ BLOCKQUOTE{margin-left:4ex;margin-right:4ex;text-align:left;} @@ -42,7 +42,7 @@ BLOCKQUOTE{margin-left:4ex;margin-right:4ex;text-align:left;}
- + logo.png
@@ -61,49 +61,50 @@ BLOCKQUOTE{margin-left:4ex;margin-right:4ex;text-align:left;} 1.1  Key Features
  • 1.2  Additional Features -
  • 2  How it works +
  • 2  How it Works -
  • 3  XML representation +
  • 3  XML Representation
  • 4  Module xml
  • 5  Module xml_stream -
  • 6  ejabberd modules +
  • 6  Modules -

    1  Introduction

    +

    1  Introduction

    - + -ejabberd is a free (GPL) distributed fault-tolerant Jabber/XMPP server and is mainly written in Erlang.
    +ejabberd is a free and open source instant messaging server written in Erlang.

    -ejabberd is designed to be a stable, standards compliant, and feature rich Jabber/XMPP server.
    +ejabberd is cross-platform, distributed, fault-tolerant, and based on open standards to achieve real-time communication.

    -ejabberd is suitable for small servers, whether they need to be scalable or not, as well as extremely big servers.
    +ejabberd is designed to be a rock-solid and feature rich XMPP server.
    +
    +ejabberd is suitable for small deployments, whether they need to be scalable or not, as well as extremely big deployments.

    -

    1.1  Key Features

    +

    1.1  Key Features

    ejabberd is:
    • -Multiplatform: ejabberd runs under Microsoft Windows and Unix derived systems such as Linux, FreeBSD and NetBSD.
      +Cross-platform: ejabberd runs under Microsoft Windows and Unix derived systems such as Linux, FreeBSD and NetBSD.

    • Distributed: You can run ejabberd on a cluster of machines and all of them will serve the same Jabber domain(s). When you need more capacity you can simply add a new cheap node to your cluster. Accordingly, you do not need to buy an expensive high-end machine to support tens of thousands concurrent users.

      -
    • Fault-tolerant: You can deploy an ejabberd cluster so that all the information required for a properly working service will be replicated permanently on all nodes. This means that if one of the nodes crashes, the others will continue working without disruption. In addition, nodes also can be added or replaced “on the fly”.
      +
    • Fault-tolerant: You can deploy an ejabberd cluster so that all the information required for a properly working service will be replicated permanently on all nodes. This means that if one of the nodes crashes, the others will continue working without disruption. In addition, nodes also can be added or replaced `on the fly'.

    • Administrator Friendly: ejabberd is built on top of the Open Source Erlang. As a result you do not need to install an external database, an external web server, amongst others because everything is already included, and ready to run out of the box. Other administrator benefits include:
      • @@ -124,17 +125,17 @@ Translated in 11 languages.
      • Open Standards: ejabberd is the first Open Source Jabber server claiming to fully comply to the XMPP standard.
        • -Fully XMPP compliant -
        • XML-based protocol +Fully XMPP compliant. +
        • XML-based protocol.
        • Many JEPs supported.
      -

      1.2  Additional Features

      +

      1.2  Additional Features

      -Besides common Jabber server features, ejabberd comes with a wide range of other features: +Moreover, ejabberd comes with a wide range of other state-of-the-art features:
      • Modular
        • @@ -152,12 +153,12 @@ SASL and STARTTLS for c2s and s2s connections. Native MySQL support.
        • Native PostgreSQL support.
        • Mnesia. -
        • ODBC data storage support. -
        • Microsoft SQL Server support (via ODBC). +
        • ODBC data storage support. +
        • Microsoft SQL Server support.
      • Authentication
        • -LDAP and ODBC. +LDAP and ODBC.
        • External Authentication script.
        • Internal Authentication.
        @@ -170,14 +171,14 @@ Compressing XML streams with Stream Compression (Multi-User Chat module with logging.
      • Users Directory based on users vCards.
      • Publish-Subscribe component. -
      • Support for virtual hosting. +
      • Support for virtual hosting.
      • HTTP Polling service.
      • IRC transport.
    - + -

    2  How it works

    +

    2  How it Works

    A Jabber domain is served by one or more ejabberd nodes. These nodes can @@ -235,9 +236,9 @@ 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.

    - + -

    3  XML representation

    +

    3  XML Representation

    Each XML stanza is represented as the following tuple: @@ -325,21 +326,14 @@ Err = term() Parses Str using XML parser, returns either parsed element or error tuple. - + -

    6  ejabberd modules

    +

    6  Modules

    - - -

    6.1  gen_mod behaviour

    - - -TBD
    -
    -

    6.2  Module gen_iq_handler

    +

    6.1  Module gen_iq_handler

    The module gen_iq_handler allows to easily write handlers for IQ packets @@ -408,12 +402,9 @@ process_local_iq(From, To, {iq, ID, Type, XMLNS, SubEl}) -> -

    6.3  Services

    +

    6.2  Services

    -TBD
    -
    -TODO: use proc_lib 
     -module(mod_echo).
 
diff --git a/doc/dev.tex b/doc/dev.tex
index 9aa3b820a..3b0764311 100644
--- a/doc/dev.tex
+++ b/doc/dev.tex
@@ -29,24 +29,31 @@
 
 %% Modules
 \newcommand{\module}[1]{\texttt{#1}}
+\newcommand{\modadhoc}{\module{mod\_adhoc}}
 \newcommand{\modannounce}{\module{mod\_announce}}
 \newcommand{\modconfigure}{\module{mod\_configure}}
 \newcommand{\moddisco}{\module{mod\_disco}}
+\newcommand{\modecho}{\module{mod\_echo}}
 \newcommand{\modirc}{\module{mod\_irc}}
 \newcommand{\modlast}{\module{mod\_last}}
+\newcommand{\modlastodbc}{\module{mod\_last\_odbc}}
 \newcommand{\modmuc}{\module{mod\_muc}}
-\newcommand{\modecho}{\module{mod\_echo}}
+\newcommand{\modmuclog}{\module{mod\_muc\_log}}
 \newcommand{\modoffline}{\module{mod\_offline}}
+\newcommand{\modofflineodbc}{\module{mod\_offline\_odbc}}
 \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{\modrosterodbc}{\module{mod\_roster\_odbc}}
 \newcommand{\modservicelog}{\module{mod\_service\_log}}
 \newcommand{\modsharedroster}{\module{mod\_shared\_roster}}
 \newcommand{\modstats}{\module{mod\_stats}}
 \newcommand{\modtime}{\module{mod\_time}}
 \newcommand{\modvcard}{\module{mod\_vcard}}
+\newcommand{\modvcardldap}{\module{mod\_vcard\_ldap}}
+\newcommand{\modvcardodbc}{\module{mod\_vcard\_odbc}}
 \newcommand{\modversion}{\module{mod\_version}}
 
 %% Title page
@@ -89,7 +96,7 @@
 % Input introduction.tex
 \input{introduction}
 
-\section{How it works}
+\section{How it Works}
 \label{sec:howitworks}
 
 
@@ -150,7 +157,7 @@ does not exist, then it is opened and registered.
 
 
 
-\section{XML representation}
+\section{XML Representation}
 \label{sec:xmlrepr}
 
 Each XML stanza is represented as the following tuple:
@@ -254,14 +261,14 @@ Err = term()
 \end{description}
 
 
-\section{\ejabberd{} modules}
+\section{Modules}
 \label{sec:emods}
 
 
-\subsection{gen\_mod behaviour}
-\label{sec:genmod}
+%\subsection{gen\_mod behaviour}
+%\label{sec:genmod}
 
-TBD
+%TBD
 
 \subsection{Module gen\_iq\_handler}
 \label{sec:geniqhandl}
@@ -345,10 +352,10 @@ process_local_iq(From, To, {iq, ID, Type, XMLNS, SubEl}) ->
 \subsection{Services}
 \label{sec:services}
 
-TBD
+%TBD
 
 
-TODO: use \verb|proc_lib|
+%TODO: use \verb|proc_lib|
 \begin{verbatim}
 -module(mod_echo).
 
diff --git a/doc/features.tex b/doc/features.tex
index d64b0fafb..f5579cf42 100644
--- a/doc/features.tex
+++ b/doc/features.tex
@@ -9,7 +9,7 @@
         Feature\ Sheet,pdfauthor=Sander\
         Devrieze,pdfsubject=ejabberd,pdfkeywords=ejabberd]{hyperref}
 \usepackage{verbatim}
-\usepackage{xcolor}
+\usepackage{color}
 
 %% Index
 % Remove the index anchors from the HTML version to save size and bandwith.
@@ -49,11 +49,14 @@
 % Options
 \newcommand{\marking}[1]{\textbf{\begin{large}\textcolor{ejblue}{#1}\end{large}}} % Marking enabled
 \newcommand{\quoting}[2][yozhik]{\begin{quotation}\textcolor{#1}{\textit{#2}}\end{quotation}} % Quotes enabled
-\newcommand{\new}{\begin{latexonly}\marginpar{\textcolor{red}{\textsc{new}}}\end{latexonly}} % Highlight new features
-\newcommand{\improved}{\begin{latexonly}\marginpar{\textcolor{orange}{\textsc{improved}}}\end{latexonly}} % Highlight improved features
-\newcommand{\moreinfo}[1]{} % Hide details
+\newcommand{\new}{\marginpar{\textcolor{red}{\textsc{new}}}} % Highlight new features
+\newcommand{\improved}{\marginpar{\textcolor{orange}{\textsc{improved}}}} % Highlight improved features
 \setcounter{secnumdepth}{-1} % Disable section numbering
 
+%% To by-pass errors in the HTML version.
+\newstyle{SPAN}{width:20\%; float:right; text-align:left; margin-left:auto;}
+\definecolor{orange}       {cmyk}{0.000,0.333,1.000,0.000}
+
 %% Footnotes
 \begin{latexonly}
 \global\parskip=9pt plus 3pt minus 1pt
@@ -67,7 +70,7 @@
 %% Fancy header
 \fancyhf{}
 \pagestyle{fancy}
-\rhead{\textcolor{ejblue}{The expandable Jabber daemon.}}
+\rhead{\textcolor{ejblue}{The Expandable Jabber Daemon.}}
 \renewcommand{\headrule}{{\color{ejblue}%
 \hrule width\headwidth height\headrulewidth \vskip-\headrulewidth}}
 \lhead{\setlength{\unitlength}{-6mm}
@@ -85,7 +88,7 @@
 
 \begin{document}
 
-\label{sec:titlepage}
+\label{titlepage}
 \begin{titlepage}
   \maketitle{}
 
@@ -107,9 +110,8 @@
 % the same identifier".
 \begin{latexonly}
 \setcounter{page}{2}
-\end{latexonly}
-
 \pagecolor{ejgreenwhite}
+\end{latexonly}
 
 % Input introduction.tex
 \input{introduction}
diff --git a/doc/guide.html b/doc/guide.html
index cf4f4382f..130a9c128 100644
--- a/doc/guide.html
+++ b/doc/guide.html
@@ -4,7 +4,7 @@
 
 
 
-Ejabberd 1.1.1 Installation and Operation Guide
+Ejabberd 1.1.2 Installation and Operation Guide
 
 
 
@@ -18,11 +18,12 @@ DIV TABLE{margin-left:inherit;margin-right:inherit;}
 PRE{text-align:left;margin-left:0ex;margin-right:auto;}
 BLOCKQUOTE{margin-left:4ex;margin-right:4ex;text-align:left;}
 .part{margin:auto;text-align:center}
+SPAN{width:20%; float:right; text-align:left; margin-left:auto;}
 
 
 
 
-
+
 
 
 
@@ -30,11 +31,11 @@ BLOCKQUOTE{margin-left:4ex;margin-right:4ex;text-align:left;}
 
 
    
 
    
-
+
    • -

    Ejabberd 1.1.1 Developers Guide

    +

    Ejabberd 1.1.2 Developers Guide

    Alexey Shchepin
    mailto:alexey@sevcom.net
    xmpp:aleksey@jabber.ru
    @@ -42,14 +43,14 @@ BLOCKQUOTE{margin-left:4ex;margin-right:4ex;text-align:left;}
    - + logo.png

    -
    I can thoroughly recommend ejabberd for ease of setup – +
    I can thoroughly recommend ejabberd for ease of setup — Kevin Smith, Current maintainer of the Psi project
    @@ -65,136 +66,159 @@ BLOCKQUOTE{margin-left:4ex;margin-right:4ex;text-align:left;} -
  • 3  Configuration +
  • 3  Basic Configuration -
  • B  Internationalization and Localization -
  • C  Release Notes +
  • A  Internationalization and Localization +
  • B  Release Notes -
  • D  Acknowledgements +
  • C  Acknowledgements +
  • D  Copyright Information -

    1  Introduction

    +

    1  Introduction

    - + -ejabberd is a free (GPL) distributed fault-tolerant Jabber/XMPP server and is mainly written in Erlang.
    +ejabberd is a free and open source instant messaging server written in Erlang.

    -ejabberd is designed to be a stable, standards compliant, and feature rich Jabber/XMPP server.
    +ejabberd is cross-platform, distributed, fault-tolerant, and based on open standards to achieve real-time communication.

    -ejabberd is suitable for small servers, whether they need to be scalable or not, as well as extremely big servers.
    +ejabberd is designed to be a rock-solid and feature rich XMPP server.
    +
    +ejabberd is suitable for small deployments, whether they need to be scalable or not, as well as extremely big deployments.

    -

    1.1  Key Features

    +

    1.1  Key Features

    ejabberd is:
    • -Multiplatform: ejabberd runs under Microsoft Windows and Unix derived systems such as Linux, FreeBSD and NetBSD.
      +Cross-platform: ejabberd runs under Microsoft Windows and Unix derived systems such as Linux, FreeBSD and NetBSD.

    • Distributed: You can run ejabberd on a cluster of machines and all of them will serve the same Jabber domain(s). When you need more capacity you can simply add a new cheap node to your cluster. Accordingly, you do not need to buy an expensive high-end machine to support tens of thousands concurrent users.

      -
    • Fault-tolerant: You can deploy an ejabberd cluster so that all the information required for a properly working service will be replicated permanently on all nodes. This means that if one of the nodes crashes, the others will continue working without disruption. In addition, nodes also can be added or replaced “on the fly”.
      +
    • Fault-tolerant: You can deploy an ejabberd cluster so that all the information required for a properly working service will be replicated permanently on all nodes. This means that if one of the nodes crashes, the others will continue working without disruption. In addition, nodes also can be added or replaced `on the fly'.

    • Administrator Friendly: ejabberd is built on top of the Open Source Erlang. As a result you do not need to install an external database, an external web server, amongst others because everything is already included, and ready to run out of the box. Other administrator benefits include:
      • Comprehensive documentation. -
      • Straightforward installers for Linux, Mac OS X, and Windows. +
      • Straightforward installers for Linux, Mac OS X, and Windows.improved
      • Web interface for administration tasks.
      • Shared Roster Groups.
      • Command line administration tool. @@ -210,17 +234,17 @@ Translated in 11 languages.
      • Open Standards: ejabberd is the first Open Source Jabber server claiming to fully comply to the XMPP standard.
        • -Fully XMPP compliant -
        • XML-based protocol +Fully XMPP compliant. +
        • XML-based protocol.
        • Many JEPs supported.
      -

      1.2  Additional Features

      +

      1.2  Additional Features

      -Besides common Jabber server features, ejabberd comes with a wide range of other features: +Moreover, ejabberd comes with a wide range of other state-of-the-art features:
      • Modular
        • @@ -238,12 +262,12 @@ SASL and STARTTLS for c2s and s2s connections. Native MySQL support.
        • Native PostgreSQL support.
        • Mnesia. -
        • ODBC data storage support. -
        • Microsoft SQL Server support (via ODBC). +
        • ODBC data storage support. +
        • Microsoft SQL Server support.new
      • Authentication
        • -LDAP and ODBC. +LDAP and ODBC.
        • External Authentication script.
        • Internal Authentication.
        @@ -253,47 +277,46 @@ Compressing XML streams with Stream Compression (Interface with networks such as AIM, ICQ and MSN.
      • Statistics via Statistics Gathering (JEP-0039).
      • IPv6 support both for c2s and s2s connections. -
      • Multi-User Chat module with logging. +
      • Multi-User Chat module with logging.improved
      • Users Directory based on users vCards.
      • Publish-Subscribe component. -
      • Support for virtual hosting. +
      • Support for virtual hosting.
      • HTTP Polling service.
      • IRC transport.
    -

    2  Installation from Source

    +

    2  Installation from Source

    - + -

    2.1  Installation Requirements

    +

    2.1  Installation Requirements

    - -

    2.1.1  “Unix-like” operating systems

    + + +

    2.1.1  `Unix-like' operating systems

    - -To compile ejabberd on a “Unix-like” operating system, you need: +To compile ejabberd on a `Unix-like' operating system, you need:
    • -GNU Make; -
    • GCC; -
    • libexpat 1.95 or higher; -
    • Erlang/OTP R9C-2 or higher; -
    • OpenSSL 0.9.6 or higher (optional). -
    • Zlib 1.2.3 or higher (optional). -
    • GNU Iconv 1.8 or higher (optional, not needed at all on systems with GNU libc). +GNU Make +
    • GCC +
    • libexpat 1.95 or higher +
    • Erlang/OTP R9C-2 or higher +
    • OpenSSL 0.9.6 or higher (optional) +
    • Zlib 1.2.3 or higher (optional) +
    • GNU Iconv 1.8 or higher (optional, not needed on systems with GNU libc)
    -

    2.1.2  Windows

    +

    2.1.2  Windows

    - To compile ejabberd on a Windows flavour, you need:
    • MS Visual C++ 6.0 Compiler @@ -307,7 +330,7 @@ MS Visual C++ 6.0 Compiler
    -

    2.2  Obtaining ejabberd

    +

    2.2  Obtaining ejabberd

    @@ -321,17 +344,16 @@ The latest development version can be retrieved from the Subversion repository. -

    2.3  Compilation

    +

    2.3  Compilation

    - + - + -

    2.3.1  “Unix-like” operating systems

    +

    2.3.1  `Unix-like' operating systems

    - - -Compile ejabberd on a “Unix-like” operating system by executing: + +Compile ejabberd on a `Unix-like' operating system by executing: 
       ./configure
   make
@@ -344,12 +366,15 @@ install ejabberd into the directory /var/lib/ejabberd,
 
  • install the configuration file into /etc/ejabberd,
 
  • create a directory called /var/log/ejabberd to store log files.
 
+Note: if you want to use an external database, you need to execute the configure
+script with the option(s) –enable-odbc or –enable-odbc
+–enable-mssql. See section 4 for more information.
    
+
    
 
 
-
    2.3.2  Windows
    
-
-
+
    2.3.2  Windows
    
 
+
 
    • 
 Install Erlang emulator (for example, into C:\Program Files\erl5.3).
 
    • Install Expat library into C:\Program Files\Expat-1.95.7
@@ -380,9 +405,10 @@ werl -s ejabberd -name ejabberd
    • -

    2.4  Starting

    +

    2.4  Starting

    + + - Execute the following command to start ejabberd: 
    @@ -391,7 +417,7 @@ Execute the following command to start ejabberd:
 
       erl -pa /var/lib/ejabberd/ebin -sname ejabberd -s ejabberd
 
    In the latter case the Erlang node will be identified using only the first part
-of the host name, i. e. other Erlang nodes outside this domain can't contact
+of the host name, i. e. other Erlang nodes outside this domain cannot contact
 this node.
    
 
    
 Note that when using the above command, ejabberd will search for the
@@ -425,16 +451,11 @@ To reduce memory usage, you may set the environment variable
   export ERL_FULLSWEEP_AFTER=0
    But in this case ejabberd can start to work slower.

    - + -

    3  Configuration

    +

    3  Basic Configuration

    - - - -

    3.1  Initial Configuration

    - - + The configuration file will be loaded the first time you start ejabberd. The content from this file will be parsed and stored in a database. Subsequently the @@ -443,7 +464,7 @@ configuration file are appended to the entries in the database. The configuration file contains a sequence of Erlang terms. Lines beginning with a `%' sign are ignored. Each term is a tuple of which the first element is the name of an option, and any further elements are that option's values. If the -configuration file do not contain for instance the “hosts” option, the old +configuration file do not contain for instance the `hosts' option, the old host name(s) stored in the database will be used.

    You can override the old values stored in the database by adding next lines to @@ -455,11 +476,11 @@ the configuration file: With these lines the old global options, local options and ACLs will be removed before new ones are added.

    - + -

    3.1.1  Host Names

    +

    3.1  Host Names

    - + The option hosts defines a list containing one or more domains that ejabberd will serve.
    @@ -467,44 +488,385 @@ The option hosts defines a list containing one or more domains that Examples:
    • Serving one domain: -
      • -
        + 
           {hosts, ["example.org"]}.
-
      • Backwards compatibility with older ejabberd versions can be retained
- with:
+
      • Serving one domain, and backwards compatible with older ejabberd + versions: 
           {host, "example.org"}.
-
      -
    • Serving two domains: +
    • Serving two domains: 
         {hosts, ["example.net", "example.com"]}.
    - + -

    3.1.2  Default Language

    +

    3.2  Virtual Hosting

    - + -The option language defines the default language of server strings that -can be seen by Jabber clients. If a Jabber client do not support -xml:lang, the specified language is used. The default value for the -option language is "en". In order to take effect there must be a -translation file <language>.msg in ejabberd's msgs directory.
    +Options can be defined separately for every virtual host using the +host_config option. It has the following +syntax: +
    +  {host_config, <hostname>, [<option>, <option>, ...]}.
+
    +Examples: +
    • +Domain example.net is using the internal authentication method while + domain example.com is using the LDAP server running on the + domain localhost to perform authentication: +
      +{host_config, "example.net", [{auth_method, internal}]}.
+
+{host_config, "example.com", [{auth_method, ldap},
+                              {ldap_servers, ["localhost"]},
+                              {ldap_uidattr, "uid"},
+                              {ldap_rootdn, "dc=localdomain"},
+                              {ldap_rootdn, "dc=example,dc=com"},
+                              {ldap_password, ""}]}.
+
    • Domain example.net is using ODBC to perform authentication + while domain example.com is using the LDAP servers running on the domains + localhost and otherhost: +
      +{host_config, "example.net", [{auth_method, odbc},
+                              {odbc_server, "DSN=ejabberd;UID=ejabberd;PWD=ejabberd"}]}.
+
+{host_config, "example.com", [{auth_method, ldap},
+                              {ldap_servers, ["localhost", "otherhost"]},
+                              {ldap_uidattr, "uid"},
+                              {ldap_rootdn, "dc=localdomain"},
+                              {ldap_rootdn, "dc=example,dc=com"},
+                              {ldap_password, ""}]}.
+
    + + +

    3.3  Listened Sockets

    + + + +The option listen defines for which addresses and ports ejabberd +will listen and what services will be run on them. Each element of the list is a +tuple with the following elements: +
    • +Port number. +
    • Module that serves this port. +
    • Options to this module. +
    + +Currently next modules are implemented: +
    + +
    • -

    Ejabberd 1.1.1 Installation and Operation Guide

    +

    Ejabberd 1.1.2 Installation and Operation Guide

    Alexey Shchepin
    mailto:alexey@sevcom.net
    xmpp:aleksey@jabber.ru
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    ejabberd_c2sDescriptionHandles c2s connections.
     Optionsaccess, certfile, inet6, + ip, max_stanza_size, shaper, ssl, + tls, starttls, starttls_required, + zlib
    ejabberd_s2s_inDescriptionHandles incoming s2s + connections.
     Optionsinet6, ip, + max_stanza_size
    ejabberd_serviceDescriptionInteracts with external + components (*).
     Optionsaccess, hosts, inet6, + ip, shaper
    ejabberd_httpDescriptionHandles incoming HTTP + connections.
     Optionscertfile, http_poll, + inet6, ip, tls, web_admin
    +
    +(*) The mechanism for external components is defined in Jabber Component Protocol (JEP-0114).
    +
    +The following options are available: +
    + {access, <access rule>}
    This option defines + access to the port. The default value is all. +
    {certfile, Path}
    Path to a file containing the SSL certificate. +
    {hosts, [Hostnames], [HostOptions]}
    This option + defines one or more hostnames of connected services and enables you to + specify additional options including {password, Secret}. +
    http_poll
    + This option enables HTTP Polling (JEP-0025) support. HTTP Polling + enables access via HTTP requests to ejabberd from behind firewalls which + do not allow outgoing sockets on port 5222.
    +
    +If HTTP Polling is enabled, it will be available at + http://server:port/http-poll/. Be aware that support for HTTP Polling + is also needed in the Jabber client. Remark also that HTTP Polling can be + interesting to host a web-based Jabber client such as + JWChat (there is a tutorial to + install JWChat with + instructions for ejabberd). +
    inet6
    Set up the socket for IPv6. +
    {ip, IPAddress}
    This option specifies which network + interface to listen for. For example {ip, {192, 168, 1, 1}}. +
    {max_stanza_size, Size}
    This + option specifies an approximate maximum size in bytes of XML stanzas. + Approximate, because it is calculated with the precision of one block of + readed data. For example {max\_stanza\_size, 65536}. The default + value is infinity. +
    {shaper, <access rule>}
    This option defines a + shaper for the port (see section 3.6). The default value + is none. +
    ssl
    This option specifies that traffic on + the port will be encrypted using SSL. You should also set the + certfile option. It is recommended to use the tls option + instead. +
    starttls
    This option + specifies that STARTTLS encryption is available on connections to the port. + You should also set the certfile option. +
    starttls_required
    This option + specifies that STARTTLS encryption is required on connections to the port. + No unencrypted connections will be allowed. You should also set the + certfile option. +
    tls
    This option specifies that traffic on + the port will be encrypted using SSL immediately after connecting. You + should also set the certfile option. +
    zlib
    This + option specifies that Zlib stream compression (as defined in JEP-0138) + is available on connections to the port. Client connections cannot use + stream compression and stream encryption simultaneously. Hence, if you + specify both tls (or ssl) and zlib, the latter + option will not affect connections (there will be no stream compression). +
    web_admin
    This option + enables the web interface for ejabberd administration which is available + at http://server:port/admin/. Login and password are the username and + password of one of the registered users who are granted access by the + `configure' access rule. +
    +In addition, the following options are available for s2s connections: +
    + {s2s_use_starttls, true|false}
    + This option defines whether to + use STARTTLS for s2s connections. +
    {s2s_certfile, Path}
    Path to a + file containing a SSL certificate. +
    {domain_certfile, Domain, Path}
    Path + to the file containing the SSL certificate for the specified domain. +
    +For instance, the following configuration defines that: +
    • +c2s connections are listened for on port 5222 and 5223 (SSL) and denied + for the user called `bad'. +
    • s2s connections are listened for on port 5269 with STARTTLS for secured + traffic enabled. +
    • Port 5280 is serving the web interface and the HTTP Polling service. Note + that it is also possible to serve them on different ports. The second + example in section 7.1 shows how exactly this can be done. +
    • All users except for the administrators have a traffic of limit + 1,000 Bytes/second +
    • The + AIM transport + aim.example.org is connected to port 5233 with password + `aimsecret'. +
    • The ICQ transport JIT (icq.example.org and + sms.example.org) is connected to port 5234 with password + `jitsecret'. +
    • The + MSN transport + msn.example.org is connected to port 5235 with password + `msnsecret'. +
    • The + Yahoo! transport + yahoo.example.org is connected to port 5236 with password + `yahoosecret'. +
    • The Gadu-Gadu transport gg.example.org is + connected to port 5237 with password `ggsecret'. +
    • The + Jabber Mail Component + jmc.example.org is connected to port 5238 with password + `jmcsecret'. +
    +
    +  {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, "jmc.example.org",
+                               [{password, "jmcsecret"}]}]}
+   ]
+  }.
+  {s2s_use_starttls, true}.
+  {s2s_certfile, "/path/to/ssl.pem"}.
+
    Note, that for jabberd 1.4- or WPJabber-based +services you have to make the transports log and do XDB by themselves: +
    +  <!--
+     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, jabberd2 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>
+
    + + +

    3.4  Authentication

    + + + +The option auth_method defines the authentication method that is used +for user authentication: +
    +  {auth_method, [<method>]}.
+
    +The following authentication methods are supported by ejabberd: + + + +

    3.4.1  Internal

    + + + +ejabberd uses its internal Mnesia database as the default authentication method. +
    • +auth_method: The value internal will enable the internal + authentication method. +
    +Examples: +
    • +To use internal authentication on example.org and LDAP + authentication on example.net: + 
      +{host_config, "example.org", [{auth_method, [internal]}]}.
+{host_config, "example.net", [{auth_method, [ldap]}]}.
+
    • To use internal authentication on all virtual hosts: + 
      +{auth_method, internal}.
+
    + + +

    3.4.2  SASL Anonymous and Anonymous Login

    + + + +The anonymous authentication method can be configured with the following +options. Remember that you can use the host_config option to set virtual +host specific options (see section 3.2). Note that there also +is a detailed tutorial regarding SASL +Anonymous and anonymous login configuration. +
    • +auth_method: The value anonymous will enable the anonymous + authentication method. +
    • allow_multiple_connections: This value for this option can be + either true or false and is only used when the anonymous mode is + enabled. Setting it to true means that the same username can be taken + multiple times in anonymous login mode if different resource are used to + connect. This option is only useful in very special occasions. The default + value is false. +
    • anonymous_protocol: This option can take three values: + sasl_anon, login_anon or both. sasl_anon means + that the SASL Anonymous method will be used. login_anon means that the + anonymous login method will be used. both means that SASL Anonymous and + login anonymous are both enabled. +
    +Those options are defined for each virtual host with the host_config +parameter (see section 3.2).

    Examples:
    • -To set Russian as default language: -
      -  {language, "ru"}.
-
    • To set Spanish as default language: -
      -  {language, "es"}.
+To enable anonymous login on all virtual hosts:
+ 
      +{auth_method, [anonymous]}.
+{anonymous_protocol, login_anon}.
+  
    • Similar as previous example, but limited to public.example.org:
+ 
      +{host_config, "public.example.org", [{auth_method, [anonymous]},
+                                     {anonymous_protocol, login_anon}]}.
+
    • To enable anonymous login and internal authentication on a virtual host:
+ 
      +{host_config, "public.example.org", [{auth_method, [anonymous,internal]},
+                                     {anonymous_protocol, login_anon}]}.
+
    • To enable SASL Anonymous on a virtual host:
+ 
      +{host_config, "public.example.org", [{auth_method, [anonymous]},
+                                     {anonymous_protocol, sasl_anon}]}.
+
    • To enable SASL Anonymous and anonymous login on a virtual host:
+ 
      +{host_config, "public.example.org", [{auth_method, [anonymous]},
+                                     {anonymous_protocol, both}]}.
+
    • To enable SASL Anonymous, anonymous login, and internal authentication on
+a virtual host:
+ 
      +{host_config, "public.example.org", [{auth_method, [anonymous,internal]},
+                                     {anonymous_protocol, both}]}.
    - + -

    3.1.3  Access Rules

    +

    3.5  Access Rules

    - + Access control in ejabberd is performed via Access Control Lists (ACLs). The declarations of ACLs in the configuration file have the following syntax: @@ -575,7 +937,8 @@ this: When a JID is checked to have access to <accessname>, the server sequentially checks if that JID mathes any of the ACLs that are named in the second elements of the tuples in the list. If it matches, the first element of -the first matched tuple is returned, otherwise “deny” is returned.
    +the first matched tuple is returned, otherwise the value `deny' is +returned.

    Example: 
    @@ -585,14 +948,14 @@ Example:
    The following access rules are pre-defined:
    -all
    Always returns “allow” -
    none
    Always returns “deny” +all
    Always returns the value `allow'. +
    none
    Always returns the value `deny'.
    - + -

    3.1.4  Shapers

    +

    3.6  Shapers

    - + Shapers enable you to limit connection traffic. The syntax of shapers is like this: @@ -607,272 +970,574 @@ second.

    Examples:
    • -To define a shaper named “normal” with traffic speed limited to +To define a shaper named `normal' with traffic speed limited to 1,000 bytes/second: 
         {shaper, normal, {maxrate, 1000}}.
-
    • To define a shaper named “fast” with traffic speed limited to +
    • To define a shaper named `fast' with traffic speed limited to 50,000 bytes/second: 
         {shaper, fast, {maxrate, 50000}}.
    - + -

    3.1.5  Limitation of the number of opened sessions

    +

    3.7  Limiting Opened Sessions

    This option specifies the maximum number of sessions (authenticated -connections) per user. If a user tries to open more than the maximum number of -allowed sessions, with different resources, the first opened session will be -disconnected. The error “session replaced” is send to the -disconnected session. This value is either a number or infinity. For -example {max\_user\_sessions, 10}. The default value is 10.
    +connections) per user. If a user tries to open more sessions by using different +resources, the first opened session will be disconnected. The error +session replaced will be sent to the disconnected session. The value +for this option can be either a number, or infinity. The default +value is 10.

    -This option can be define per virtual host. See section 3.1.8.
    -
    - - -

    3.1.6  Listened Sockets

    - - - -The option listen defines for which addresses and ports ejabberd -will listen and what services will be run on them. Each element of the list is a -tuple with the following elements: +Examples:
    • -Port number. -
    • Module that serves this port. -
    • Options to this module. -
    - -Currently next modules are implemented: -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    ejabberd_c2sDescriptionHandles c2s connections.
     Optionsaccess, certfile, inet6, - ip, max_stanza_size, shaper, ssl, - tls, starttls, starttls_required, - zlib
    ejabberd_s2s_inDescriptionHandles incoming s2s - connections.
     Optionsinet6, ip, - max_stanza_size
    ejabberd_serviceDescriptionInteracts with external - components (*).
     Optionsaccess, hosts, inet6, - ip, shaper
    ejabberd_httpDescriptionHandles incoming HTTP - connections.
     Optionscertfile, http_poll, - inet6, ip, tls, web_admin
    -
    -(*) The mechanism for external components is defined in Jabber Component Protocol (JEP-0114).
    -
    -The following options are available: -
    - {access, <access rule>}
    This option defines - access to the port. The default value is “all”. -
    {certfile, Path}
    Path to a file containing the SSL certificate. -
    {hosts, [Hostnames], [HostOptions]}
    This option - defines one or more hostnames of connected services and enables you to - specify additional options including {password, Secret}. -
    http_poll
    - This option enables HTTP Polling (JEP-0025) support. HTTP Polling - enables access via HTTP requests to ejabberd from behind firewalls which - do not allow outgoing sockets on port 5222.
    -
    -If HTTP Polling is enabled, it will be available at - http://server:port/http-poll/. Be aware that support for HTTP Polling - is also needed in the Jabber client. Remark also that HTTP Polling can be - interesting to host a web-based Jabber client such as - JWChat (there is a tutorial to - install JWChat with - instructions for ejabberd). -
    inet6
    Set up the socket for IPv6. -
    {ip, IPAddress}
    This option specifies which network - interface to listen for. For example {ip, {192, 168, 1, 1}}. -
    {max_stanza_size, Size}
    This - option specifies an approximate maximal size in bytes of XML stanzas. - For example {max\_stanza\_size, 65536}. The default value - is “infinity”. -
    {shaper, <access rule>}
    This option defines a - shaper for the port (see section 3.1.4). The default value - is “none”. -
    ssl
    This option specifies that traffic on - the port will be encrypted using SSL. You should also set the - certfile option. It is recommended to use the tls option - instead. -
    starttls
    This option - specifies that STARTTLS encryption is available on connections to the port. - You should also set the certfile option. -
    starttls_required
    This option - specifies that STARTTLS encryption is required on connections to the port. - No unencrypted connections will be allowed. You should also set the - certfile option. -
    tls
    This option specifies that traffic on - the port will be encrypted using SSL immediately after connecting. You - should also set the certfile option. -
    zlib
    This - option specifies that Zlib stream compression (as defined in JEP-0138) - is available on connections to the port. Client cannot use stream compression and - stream encryption simultaneously, so if you specify both tls (or ssl) - and zlib the latter option will not affect connection at all. -
    web_admin
    This option - enables the web interface for ejabberd administration which is available - at http://server:port/admin/. Login and password are the username and - password of one of the registered users who are granted access by the - “configure” access rule. -
    -Also the following global options are available for s2s connections: -
    - {s2s_use_starttls, true|false}
    - This option defines whether to use STARTTLS - for s2s connections. -
    {s2s_certfile, Path}
    Path to the - file containing the SSL certificate. -
    {domain_certfile, Domain, Path}
    Path - to the file containing the SSL certificate for the specified domain. -
    -For instance, the following configuration defines that: -
    • -c2s connections are listened for on port 5222 and 5223 (SSL) and denied - for the user “bad” -
    • s2s connections are listened for on port 5269 with STARTTLS for secured - traffic enabled. -
    • Port 5280 is serving the web interface and the HTTP Polling service. Note - that it is also possible to serve them on different ports. The second - example in section 3.4.1 shows how exactly this can be done. -
    • All users except for the administrators have a traffic of limit - 1,000 Bytes/second -
    • The - AIM transport - aim.example.org is connected to port 5233 with password - “aimsecret” -
    • The ICQ transport JIT (icq.example.org and - sms.example.org) is connected to port 5234 with password - “jitsecret” -
    • The - MSN transport - msn.example.org is connected to port 5235 with password - “msnsecret” -
    • The - Yahoo! transport - yahoo.example.org is connected to port 5236 with password - “yahoosecret” -
    • The Gadu-Gadu transport gg.example.org is - connected to port 5237 with password “ggsecret” -
    • The - Jabber Mail Component - jmc.example.org is connected to port 5238 with password - “jmcsecret” -
    +To limit the number of sessions per user to 10 on all virtual +hosts: 
    -  {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, "jmc.example.org",
-                               [{password, "jmcsecret"}]}]}
+  {max\_user\_sessions, 10}.
+
  • This option can be defined per virtual host (see +section 3.2). In next example the number of +sessions per user on the first host is six, while there is no limit on the +second host: +
    +  {host_config, "example.net", [{max\_user\_sessions, 6}]}.
+  {host_config, "example.com", [{max\_user\_sessions, infinity}]}.
+
    + + +

    3.8  Default Language

    + + + +The option language defines the default language of server strings that +can be seen by Jabber clients. If a Jabber client do not support +xml:lang, the specified language is used. The default value is +en. In order to take effect there must be a translation file +<language>.msg in ejabberd's msgs directory.
    +
    +Examples: +
    • +To set Russian as default language: +
      +  {language, "ru"}.
+
    • To set Spanish as default language: +
      +  {language, "es"}.
+
    + + +

    4  Database Configuration

    + + + + +ejabberd uses its internal Mnesia database by default. However, it is +possible to use a relational database or an LDAP server to store persistant, +long-living data. ejabberd is very flexible: you can configure different +authentication methods for different virtual hosts, you can configure different +authentication mechanisms for the same virtual host (fallback), you can set +different storage systems for modules, and so forth.
    +
    +The following databases are supported by ejabberd: + +The following LDAP servers are tested with ejabberd: +
    • +Active Directory + (see section 4.5.3) +
    • OpenLDAP +
    • Normally any LDAP compatible server should work; inform us about your + success with a not-listed server so that we can list it here. +
    + + +

    4.1  MySQL

    + + + +Although this section will describe ejabberd's configuration when you want to +use the native MySQL driver, it does not describe MySQL's installation and +database creation. Check the MySQL documentation and the tutorial Using ejabberd with MySQL native driver for information regarding these topics. +Note that the tutorial contains information about ejabberd's configuration +which is duplicate to this section.
    +
    +Moreover, the file mysql.sql in the directory src/odbc might be interesting for +you. This file contains the ejabberd schema for MySQL. At the end of the file +you can find information to update your database schema.
    +
    + + +

    4.1.1  Driver Compilation

    + + + +You can skip this step if you installed ejabberd using a binary installer or +if the binary packages of ejabberd you are using include support for MySQL. +
    1. +First, install the Erlang + MySQL library. Make sure the compiled files are in your Erlang path; you can + put them for example in the same directory as your ejabberd .beam files. +
    2. Then, configure and install ejabberd with ODBC support enabled (this is + also needed for native MySQL support!). This can be done, by using next + commands: + 
      +./configure --enable-odbc && make install
+
    + + +

    4.1.2  Authentication

    + + + +The option value name may be misleading, as the auth_method name is used +for access to a relational database through ODBC, as well as through the native +MySQL interface. Anyway, the first configuration step is to define the odbc +auth_method. For example: +
    +{host_config, "public.example.org", [{auth_method, [odbc]}]}.
+
    +The actual database access is defined in the option odbc_server. Its +value is used to define if we want to use ODBC, or one of the two native +interface available, PostgreSQL or MySQL.
    +
    +To use the native MySQL interface, you can pass a tuple of the following form as +parameter: +
    +{mysql, "Server", "Database", "Username", "Password"}
+
    +mysql is a keyword that should be kept as is. For example: +
    +{odbc_server, {mysql, "localhost", "test", "root", "password"}}.
+
    + + +

    4.1.3  Storage

    + + + +MySQL also can be used to store information into from several ejabberd +modules. See section 5.1 to see which modules have a version +with the `_odbc'. This suffix indicates that the module can be used with +relational databases like MySQL. To enable storage to your database, just make +sure that your database is running well (see previous sections), and replace the +suffix-less or ldap module variant with the odbc module variant. Keep in mind +that you cannot have several variants of the same module loaded!
    +
    + + +

    4.2  Microsoft SQL Server

    + + + +Although this section will describe ejabberd's configuration when you want to +use Microsoft SQL Server, it does not describe Microsoft SQL Server's +installation and database creation. Check the MySQL documentation and the +tutorial Using ejabberd with MySQL native driver for information regarding these topics. +Note that the tutorial contains information about ejabberd's configuration +which is duplicate to this section.
    +
    +Moreover, the file mssql.sql in the directory src/odbc might be interesting for +you. This file contains the ejabberd schema for Microsoft SQL Server. At the end +of the file you can find information to update your database schema.
    +
    + + +

    4.2.1  Driver Compilation

    + + + +You can skip this step if you installed ejabberd using a binary installer or +if the binary packages of ejabberd you are using include support for ODBC.
    +
    +If you want to use Microsoft SQL Server with ODBC, you need to configure, +compile and install ejabberd with support for ODBC and Microsoft SQL Server +enabled. This can be done, by using next commands: +
    +./configure --enable-odbc --enable-mssql && make install
+
    + + +

    4.2.2  Authentication

    + + + +The configuration of Microsoft SQL Server is the same as the configuration of +ODBC compatible serers (see section 4.4.2).
    +
    + + +

    4.2.3  Storage

    + + + +Microsoft SQL Server also can be used to store information into from several +ejabberd modules. See section 5.1 to see which modules have +a version with the `_odbc'. This suffix indicates that the module can be used +with relational databases like Microsoft SQL Server. To enable storage to your +database, just make sure that your database is running well (see previous +sections), and replace the suffix-less or ldap module variant with the odbc +module variant. Keep in mind that you cannot have several variants of the same +module loaded!
    +
    + + +

    4.3  PostgreSQL

    + + + +Although this section will describe ejabberd's configuration when you want to +use the native PostgreSQL driver, it does not describe PostgreSQL's installation +and database creation. Check the PostgreSQL documentation and the tutorial Using ejabberd with MySQL native driver for information regarding these topics. +Note that the tutorial contains information about ejabberd's configuration +which is duplicate to this section.
    +
    +Also the file pg.sql in the directory src/odbc might be interesting for you. +This file contains the ejabberd schema for PostgreSQL. At the end of the file +you can find information to update your database schema.
    +
    + + +

    4.3.1  Driver Compilation

    + + + +You can skip this step if you installed ejabberd using a binary installer or +if the binary packages of ejabberd you are using include support for +PostgreSQL. +
    1. +First, install the Erlang PgSQL library from + Jungerl. Make sure the compiled + files are in your Erlang path; you can put them for example in the same + directory as your ejabberd .beam files. +
    2. Then, configure, compile and install ejabberd with ODBC support enabled + (this is also needed for native PostgreSQL support!). This can be done, by + using next commands: + 
      +./configure --enable-odbc && make install
+
    + + +

    4.3.2  Authentication

    + + + +The option value name may be misleading, as the auth_method name is used +for access to a relational database through ODBC, as well as through the native +PostgreSQL interface. Anyway, the first configuration step is to define the odbc +auth_method. For example: +
    +{host_config, "public.example.org", [{auth_method, [odbc]}]}.
+
    +The actual database access is defined in the option odbc_server. Its +value is used to define if we want to use ODBC, or one of the two native +interface available, PostgreSQL or MySQL.
    +
    +To use the native PostgreSQL interface, you can pass a tuple of the following +form as parameter: +
    +{pgsql, "Server", "Database", "Username", "Password"}
+
    +pgsql is a keyword that should be kept as is. For example: +
    +{odbc_server, {pgsql, "localhost", "database", "ejabberd", "password"}}.
+
    + + +

    4.3.3  Storage

    + + + +PostgreSQL also can be used to store information into from several ejabberd +modules. See section 5.1 to see which modules have a version +with the `_odbc'. This suffix indicates that the module can be used with +relational databases like PostgreSQL. To enable storage to your database, just +make sure that your database is running well (see previous sections), and +replace the suffix-less or ldap module variant with the odbc module variant. +Keep in mind that you cannot have several variants of the same module loaded!
    +
    + + +

    4.4  ODBC Compatible

    + + + +Although this section will describe ejabberd's configuration when you want to +use the ODBC driver, it does not describe the installation and database creation +of your database. Check the documentation of your database. The tutorial Using ejabberd with MySQL native driver also can help you. Note that the tutorial +contains information about ejabberd's configuration which is duplicate to +this section.
    +
    + + +

    4.4.1  Compilation

    + + +You can skip this step if you installed ejabberd using a binary installer or +if the binary packages of ejabberd you are using include support for +ODBC. +
    1. +First, install the Erlang + MySQL library. Make sure the compiled files are in your Erlang path; you can + put them for example in the same directory as your ejabberd .beam files. +
    2. Then, configure, compile and install ejabberd with ODBC support + enabled. This can be done, by using next commands: + 
      +./configure --enable-odbc && make install
+
    + + +

    4.4.2  Authentication

    + + + +The first configuration step is to define the odbc auth_method. For +example: +
    +{host_config, "public.example.org", [{auth_method, [odbc]}]}.
+
    +The actual database access is defined in the option odbc_server. Its +value is used to defined if we want to use ODBC, or one of the two native +interface available, PostgreSQL or MySQL.
    +
    +To use a relational database through ODBC, you can pass the ODBC connection +string as odbc_server parameter. For example: +
    +{odbc_server, "DSN=database;UID=ejabberd;PWD=password"}.
+
    + + +

    4.4.3  Storage

    + + + +An ODBC compatible database also can be used to store information into from +several ejabberd modules. See section 5.1 to see which +modules have a version with the `_odbc'. This suffix indicates that the module +can be used with ODBC compatible relational databases. To enable storage to your +database, just make sure that your database is running well (see previous +sections), and replace the suffix-less or ldap module variant with the odbc +module variant. Keep in mind that you cannot have several variants of the same +module loaded!
    +
    + + +

    4.5  LDAP

    + + + +ejabberd has built-in LDAP support. You can authenticate users against LDAP +server and use LDAP directory as vCard storage. Shared rosters are not supported +yet.
    +
    + + +

    4.5.1  Connection

    + + +Parameters: +
    +ldap_server
    IP address or dns name of your +LDAP server. This option is required. +
    ldap_port
    Port to connect to your LDAP server. + The default value is 389. +
    ldap_rootdn
    Bind DN. The default value + is "" which means `anonymous connection'. +
    ldap_password
    Bind password. The default + value is "". +
    +Example: +
    +  {auth_method, ldap}.
+  {ldap_servers, ["ldap.example.org"]}.
+  {ldap_port, 389}.
+  {ldap_rootdn, "cn=Manager,dc=domain,dc=org"}.
+  {ldap_password, "secret"}.
+
    +Note that current LDAP implementation does not support SSL secured communication +and SASL authentication.
    +
    + + +

    4.5.2  Authentication

    + + +You can authenticate users against an LDAP directory. Available options are: +
    +ldap_base
    LDAP base directory which stores users + accounts. This option is required. +
    ldap_uidattr
    LDAP attribute which holds + the user's part of a JID. The default value is "uid". +
    ldap_uidattr_format
    Format of the + ldap_uidattr variable. The format must contain one and only one + pattern variable "%u" which will be replaced by the user's part of a + JID. For example, "%u@example.org". The default value is "%u". +
    ldap_filter
    + RFC 2254 LDAP filter. The + default is none. Example: + "(&(objectClass=shadowAccount)(memberOf=Jabber Users))". Please, do + not forget to close brackets and do not use superfluous whitespaces. Also you + must not use ldap_uidattr attribute in filter because this + attribute will be substituted in LDAP filter automatically. +
    + + +

    4.5.3  Examples

    + + + + +
    Common example
    + +Let's say ldap.example.org is the name of our LDAP server. We have +users with their passwords in "ou=Users,dc=example,dc=org" directory. +Also we have addressbook, which contains users emails and their additional +infos in "ou=AddressBook,dc=example,dc=org" directory. Corresponding +authentication section should looks like this: +
    +  %% authentication method
+  {auth_method, ldap}.
+  %% DNS name of our LDAP server
+  {ldap_servers, ["ldap.example.org"]}.
+  %% Bind to LDAP server as "cn=Manager,dc=example,dc=org" with password "secret"
+  {ldap_rootdn, "cn=Manager,dc=example,dc=org"}.
+  {ldap_password, "secret"}.
+  %% define the user's base
+  {ldap_base, "ou=Users,dc=example,dc=org"}.
+  %% We want to authorize users from 'shadowAccount' object class only
+  {ldap_filter, "(objectClass=shadowAccount)"}.
+
    +Now we want to use users LDAP-info as their vCards. We have four attributes +defined in our LDAP schema: "mail" — email address, "givenName" +— first name, "sn" — second name, "birthDay" — birthday. +Also we want users to search each other. Let's see how we can set it up: +
    +  {modules,
+    ...
+    {mod_vcard_ldap,
+     [
+      %% We use the same server and port, but want to bind anonymously because
+      %% our LDAP server accepts anonymous requests to
+      %% "ou=AddressBook,dc=example,dc=org" subtree.
+      {ldap_rootdn, ""},
+      {ldap_password, ""},
+      %% define the addressbook's base
+      {ldap_base, "ou=AddressBook,dc=example,dc=org"},
+      %% user's part of JID is located in the "mail" attribute
+      {ldap_uidattr, "mail"},
+      %% common format for our emails
+      {ldap_uidattr_format, "%u@mail.example.org"},
+      %% We have to define empty filter here, because entries in addressbook does not
+      %% belong to shadowAccount object class
+      {ldap_filter, ""},
+      %% Now we want to define vCard pattern
+      {ldap_vcard_map,
+       [{"NICKNAME", "%u", []}, % just use user's part of JID as his nickname
+        {"GIVEN", "%s", ["givenName"]},
+        {"FAMILY", "%s", ["sn"]},
+        {"FN", "%s, %s", ["sn", "givenName"]}, % example: "Smith, John"
+        {"EMAIL", "%s", ["mail"]},
+        {"BDAY", "%s", ["birthDay"]}]},
+      %% Search form
+      {ldap_search_fields,
+       [{"User", "%u"},
+        {"Name", "givenName"},
+        {"Family Name", "sn"},
+        {"Email", "mail"},
+        {"Birthday", "birthDay"}]},
+      %% vCard fields to be reported
+      %% Note that JID is always returned with search results
+      {ldap_search_reported,
+       [{"Full Name", "FN"},
+        {"Nickname", "NICKNAME"},
+        {"Birthday", "BDAY"}]}
+    ]}
+    ...
+  }.
+
    +Note that mod_vcard_ldap module checks for the existence of the user before +searching in his information in LDAP.
    +
    + + +
    Active Directory
    + + + +Active Directory is just an LDAP-server with predefined attributes. A sample +configuration is showed below: +
    +  {auth_method, ldap}.
+  {ldap_servers, ["office.org"]}.    % List of LDAP servers
+  {ldap_base, "DC=office,DC=org"}. % Search base of LDAP directory
+  {ldap_rootdn, "CN=Administrator,CN=Users,DC=office,DC=org"}. % LDAP manager
+  {ldap_password, "*******"}. % Password to LDAP manager
+  {ldap_uidattr, "sAMAccountName"}.
+  {ldap_filter, "(memberOf=*)"}.
+  
+  {mod_vcard_ldap,
+   [{ldap_vcard_map,
+     [{"NICKNAME", "%u", []},
+      {"GIVEN", "%s", ["givenName"]},
+      {"MIDDLE", "%s", ["initials"]},
+      {"FAMILY", "%s", ["sn"]},
+      {"FN", "%s", ["displayName"]},
+      {"EMAIL", "%s", ["mail"]},
+      {"ORGNAME", "%s", ["company"]},
+      {"ORGUNIT", "%s", ["department"]},
+      {"CTRY", "%s", ["c"]},
+      {"LOCALITY", "%s", ["l"]},
+      {"STREET", "%s", ["streetAddress"]},
+      {"REGION", "%s", ["st"]},
+      {"PCODE", "%s", ["postalCode"]},
+      {"TITLE", "%s", ["title"]},
+      {"URL", "%s", ["wWWHomePage"]},
+      {"DESC", "%s", ["description"]},
+      {"TEL", "%s", ["telephoneNumber"]}]},
+    {ldap_search_fields,
+     [{"User", "%u"},
+      {"Name", "givenName"},
+      {"Family Name", "sn"},
+      {"Email", "mail"},
+      {"Company", "company"},
+      {"Department", "department"},
+      {"Role", "title"},
+      {"Description", "description"},
+      {"Phone", "telephoneNumber"}]},
+    {ldap_search_reported,
+     [{"Full Name", "FN"},
+      {"Nickname", "NICKNAME"},
+      {"Email", "EMAIL"}]}
    ]
   }.
-  {s2s_use_starttls, true}.
-  {s2s_certfile, "/path/to/ssl.pem"}.
-
    Note, that for jabberd 1.4- or WPJabber-based -services you have to make the transports log and do XDB by themselves: -
    -  <!--
-     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, jabberd2 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>
    - + -

    3.1.7  Modules

    +

    5  Modules Configuration

    - + The option modules defines the list of modules that will be loaded after ejabberd's startup. Each entry in the list is a tuple in which the first element is the name of a module and the second is a list of options for that -module. Read section A for detailed information about modules.
    +module.

    Examples:
    • -In this simple example, only the module mod_echo is loaded and no - options are specified between square brackets: +In this example only the module mod_echo is loaded and no module + options are specified between the square brackets: 
         {modules,
    [{mod_echo,      []}
    ]}.
-
    • The second example is also simple: the modules mod_echo, mod_time, and +
    • In the second example the modules mod_echo, mod_time, and mod_version are loaded without options. Remark that, besides the last entry, all entries end with a comma: 
      @@ -882,187 +1547,28 @@ In this simple example, only the module mod_echo is loaded and no
     {mod_version,   []}
    ]}.
    - + -

    3.1.8  Virtual Hosting

    +

    5.1  Overview

    - + -Options can be defined separately for every virtual host using the -host_config option. It has the following -syntax: -
    -  {host_config, <hostname>, [<option>, <option>, ...]}.
-
    -Examples: +The following table lists all modules available in the official ejabberd +distribution. You can find more +contributed modules on the +ejabberd website. Please remember that these contributions might not work or +that they can contain severe bugs and security leaks. Therefore, use them at +your own risk!
    +
    +You can see which database backend each module needs by looking at the suffix:
    • -Domain example.net is using the internal authentication method while - domain example.com is using the LDAP server running on the domain - localhost to perform authentication: -
      -{host_config, "example.net", [{auth_method, internal}]}.
-
-{host_config, "example.com", [{auth_method, ldap},
-                              {ldap_servers, ["localhost"]},
-                              {ldap_uidattr, "uid"},
-                              {ldap_rootdn, "dc=localdomain"},
-                              {ldap_rootdn, "dc=example,dc=com"},
-                              {ldap_password, ""}]}.
-
    • Domain example.net is using ODBC to perform authentication - while domain example.com is using the LDAP servers running on the domains - localhost and otherhost: -
      -{host_config, "example.net", [{auth_method, odbc},
-                              {odbc_server, "DSN=ejabberd;UID=ejabberd;PWD=ejabberd"}]}.
-
-{host_config, "example.com", [{auth_method, ldap},
-                              {ldap_servers, ["localhost", "otherhost"]},
-                              {ldap_uidattr, "uid"},
-                              {ldap_rootdn, "dc=localdomain"},
-                              {ldap_rootdn, "dc=example,dc=com"},
-                              {ldap_password, ""}]}.
-
    - - -

    3.1.9  SASL anonymous and anonymous login

    - - - -The configuration of the anonymous mode can be done with three -host_config parameters: -
    • -auth_method: This value is used for defining the authentication method: -internal, odbc, ldap, external). You now have a special extra option to enable -anonymous mode: anonymous.
      -
      -
    • allow_multiple_connections: This option can be either true or false and -is only used when the anonymous mode is enabled. Setting it to true means that -the same username will be able to be taken several time in anonymous login -mode if different resource are used to connect. This option is only useful in -very special cases. It defaults to false.
      -
      -
    • anonymous_protocol: This option can take three values: - sasl_anon, login_anon or both. sasl_anon means that - SASL anonymous mode is enabled. login_anon means that anonymous - login mode is enabled. both means that SASL anonymous and login anonymous are - enabled. +`_ldap', this means that the module needs an LDAP server as backend. +
    • `_odbc', this means that the module needs a supported database + (see 4) as backend. +
    • No suffix, this means that the modules uses Erlang's built-in database + Mnesia as backend.
    -Those options are defined for each virtual host with the host_config -parameter (see section 3.1.8).
    -
    -Examples: -
    • -To enable anonymous login on a virtual host: -
      -{host_config, "public.example.org", [{auth_method, anonymous},
-                                     {anonymous_protocol, login_anon}]}.
-
    • To enable anonymous login and internal authentication on a virtual host: -
      -{host_config, "public.example.org", [{auth_method, [anonymous,internal]},
-                                     {anonymous_protocol, login_anon}]}.
-
    • To enable SASL anonymous on a virtual host: -
      -{host_config, "public.example.org", [{auth_method, [anonymous]},
-                                     {anonymous_protocol, sasl_anon}]}.
-
    • To enable SASL anonymous and anonymous login on a virtual host: -
      -{host_config, "public.example.org", [{auth_method, [anonymous]},
-                                     {anonymous_protocol, both}]}.
-
    • To enable SASL anonymous, anonymous login and internal authentication on -a virtual host: -
      -{host_config, "public.example.org", [{auth_method, [anonymous,internal]},
-                                     {anonymous_protocol, both}]}.
-
    -A detailled tutorial on SASL anonymous and anonymous login support is -available from: -http://support.process-one.net/doc/display/MESSENGER/Anonymous+users+support
    -
    - - -

    3.2  Relational Database Support

    - - - - -

    3.2.1  Preliminary steps

    - - -If you have installed ejabberd using a binary version, the compilation steps -are not needed as they have already been done correctly.
    -
    -Otherwise, to be able to use ejabberd with a relational database you need to -enable ODBC modules during compilation, even if you want to use ejabberd with -MySQL or PostgreSQL in native mode. The following configure command can -be used to enable the relational modules: -
    -./configure --enable-odbc
-
    -If you are planning to use Microsoft SQL Server with ODBC, you need to specify -it from the configure command before compilation: -
    -./configure --enable-odbc --enable-mssql
-
    - - -

    3.2.2  Authentication against a relational database

    - - -ejabberd use its internal Mnesia database as a default. It is however possible -to use relational database to store persistant, long-living data. When -switching the auth_method from internal to odbc, you are -telling ejabberd to use a relational database for authentication. Different -auth_method values can be used for different virtual hosts in the -system.
    -
    -The option value name be misleading, as the method name is use both for access -to relational database through ODBC or through the native interface. In any -case, the first step is to define the odbc auth_method. For example: -
    -{host_config, "public.example.org", [{auth_method, [odbc]}]}.
-
    -The actual database access is defined in the option odbc_server. Its -value is use to defined if we want to use ODBC, or one of the two native -interface available, PostgreSQL or MySQL.
    -
    -To use a relational database through ODBC, you can pass the ODBC connection -string as odbc_server parameter. For example: -
    -{odbc_server, "DSN=database;UID=ejabberd;PWD=password"}.
-
    -To use the native PostgreSQL interface, you can pass a tuple of the following form as -parameter: -
    -{pgsql, "Server", "Database", "Username", "Password"}
-
    -pgsql is a keyword that should be kept as is. For example: -
    -{odbc_server, {pgsql, "localhost", "database", "ejabberd", "password"}}.
-
    -Note that you need to install the Erlang PgSQL library first. This library is -available from Sourceforge: http://cvs.sourceforge.net/viewcvs.py/jungerl/jungerl/lib/pgsql/
    -
    -To use the native MySQL interface, the same tuple should be passed, except -that you now have to use the mysql keyword instead of the pgsql -keyword: -
    -{mysql, "Server", "Database", "Username", "Password"}
-
    -mysql is a keyword that should be kept as is. For example: -
    -{odbc_server, {mysql, "localhost", "test", "root", "password"}}.
-
    -Note that you need to install the Erlang MySQL library first. This library is -directly available from Process-one website: http://support.process-one.net/doc/display/CONTRIBS/Yxa
    -
    -A detailled tutorial to set-up ejabberd using the native MySQL interface is -available from: http://support.process-one.net/doc/display/MESSENGER/Using+ejabberd+with+MySQL+native+driver
    -
    - - -

    3.2.3  Relational database for other modules

    - - +If you want to It is possible to use a relational database to store pieces of information. You can do this by changing the module name to a name with an _odbc suffix in ejabberd config file. You can use a relational @@ -1075,373 +1581,6 @@ Last connection date and time: Use mod_last_odbc instead of
  • Rosters: Use mod_roster_odbc instead of mod_roster.
  • Users' VCARD: Use mod_vcard_odbc instead of mod_vcard. - - -

    3.3  Creating an Initial Administrator

    - - -Before the web interface can be entered to perform administration tasks, an -account with administrator rights is needed on your ejabberd deployment.
    -
    -Instructions to create an initial administrator account: -
    1. -Register an account on your ejabberd deployment. An account can be - created in two ways: -
      1. - Using the tool ejabberdctl (see - section 3.4.2): - 
        -% ejabberdctl node@host register admin example.org password
-
      2. Using In-Band Registration (see section A.14): you can - use a Jabber client to register an account. -
      -
    2. Edit the configuration file to promote the account created in the previous - step to an account with administrator rights. Note that if you want to add - more administrators, a seperate acl entry is needed for each administrator. - 
      -  {acl, admins, {user, "admin", "example.org"}}.
-  {access, configure, [{allow, admins}]}.
-
    3. Restart ejabberd to load the new configuration. -
    4. Open the web interface (http://server:port/admin/) in your - favourite browser. Make sure to enter the full JID as username (in this - example: admin@example.org. The reason that you also need to enter the - suffix, is because ejabberd's virtual hosting support. -
    - - -

    3.4  Online Configuration and Monitoring

    - - - - -

    3.4.1  Web Interface

    - - - -To perform online configuration of ejabberd you need to enable the -ejabberd_http listener with the option web_admin (see -section 3.1.6). Then you can open -http://server:port/admin/ in your favourite web browser. You -will be asked to enter the username (the full Jabber ID) and password -of an ejabberd user with administrator rights. After authentication -you will see a page similar to figure 1. -
    - - - - -
    -
    -
    Figure 1: Top page from the web interface

    -
    - - -
    -Here you can edit access restrictions, manage users, create backups, -manage the database, enable/disable ports listened for, view server -statistics,...
    -
    -Examples: -
    • -You can serve the web interface on the same port as the - HTTP Polling interface. In this example - you should point your web browser to http://example.org:5280/admin/ to - administer all virtual hosts or to - http://example.org:5280/admin/server/example.com/ to administer only - the virtual host example.com. Before you get access to the web interface - you need to enter as username, the JID and password from a registered user - that is allowed to configure ejabberd. In this example you can enter as - username “admin@example.net” to administer all virtual hosts (first - URL). If you log in with “admin@example.com” on
      -http://example.org:5280/admin/server/example.com/ you can only - administer the virtual host example.com. - 
      -  ...
-  {acl, admins, {user, "admin", "example.net"}}.
-  {host_config, "example.com", [{acl, admins, {user, "admin", "example.com"}}]}.
-  {access, configure, [{allow, admins}]}.
-  ...
-  {hosts, ["example.org"]}.
-  ...
-  {listen,
-   [...
-    {5280, ejabberd_http, [http_poll, web_admin]},
-    ...
-   ]
-  }.
-
    • For security reasons, you can serve the web interface on a secured - connection, on a port differing from the HTTP Polling interface, and bind it - to the internal LAN IP. The web interface will be accessible by pointing your - web browser to https://192.168.1.1:5280/admin/: - 
      -  ...
-  {hosts, ["example.org"]}.
-  ...
-  {listen,
-   [...
-    {5270, ejabberd_http,    [http_poll]},
-    {5280, ejabberd_http,    [web_admin, {ip, {192, 168, 1, 1}},
-                              tls, {certfile, "/usr/local/etc/server.pem"}]},
-    ...
-   ]
-  }.
-
    - - -

    3.4.2  ejabberdctl

    - - -It is possible to do some administration operations using the command -line tool ejabberdctl. You can list all available options by -running ejabberdctl without arguments: -
    -% ejabberdctl
-Usage: ejabberdctl node command
-
-Available commands:
-  status                        get ejabberd status
-  stop                          stop ejabberd
-  restart                       restart ejabberd
-  reopen-log                    reopen log file
-  register user server password register a user
-  unregister user server        unregister a user
-  backup file                   store a database backup to file
-  restore file                  restore a database backup from file
-  install-fallback file         install a database fallback from file
-  dump file                     dump a database to a text file
-  load file                     restore a database from a text file
-  import-file file              import user data from jabberd 1.4 spool file
-  import-dir dir                import user data from jabberd 1.4 spool directory
-  registered-users              list all registered users
-  delete-expired-messages       delete expired offline messages from database
-
-Example:
-  ejabberdctl ejabberd@host restart
-
    -Additional information: -
    -reopen-log
    If you use a tool to rotate logs, you have to configure it - so that this command is executed after each rotation. -
    backup, restore, install-fallback, dump, load
    You can use these - commands to create and restore backups. -
    import-file, import-dir
    - These options can be used to migrate from other Jabber/XMPP servers. There - exist tutorials to migrate from jabberd 1.4 - and to migrate from jabberd2. -
    delete-expired-messages
    This option can be used to delete old messages - in offline storage. This might be useful when the number of offline messages - is very high. -
    - - -

    4  Firewall Settings

    - - - -You need to take the following TCP ports in mind when configuring your firewall: -
    - - - - - - - - - - - - - - - - - - -
    PortDescription
    5222SASL and unencrypted c2s connections.
    5223Obsolete SSL c2s connections.
    5269s2s connections.
    4369Only for clustering (see 6).
    port rangeOnly for clustring (see 6). This range - is configurable (see 2.4).
    -
    - - -

    5  SRV Records

    - - - - - - -

    6  Clustering

    - - - - - -

    6.1  How it Works

    - - - -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 ~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...
    -
    -Each ejabberd node has the following modules: -
    • -router, -
    • local router, -
    • session manager, -
    • s2s manager. -
    - - -

    6.1.1  Router

    - - -This module is the main router of Jabber packets on each node. It -routes them based on their destination's domains. It uses a global -routing table. The domain of the packet's destination is searched in the -routing table, and if it is found, the packet is routed to the -appropriate process. If not, it is sent to the s2s manager.
    -
    - - -

    6.1.2  Local Router

    - - -This module routes packets which have a destination domain equal to -one of this server's host names. If the destination JID has a non-empty user -part, it is routed to the session manager, otherwise it is processed depending -on its content.
    -
    - - -

    6.1.3  Session Manager

    - - -This module routes packets to local users. It looks up to which user -resource a packet must be sent via a presence table. Then the packet is -either routed to the appropriate c2s process, or stored in offline -storage, or bounced back.
    -
    - - -

    6.1.4  s2s Manager

    - - -This module routes packets to other Jabber servers. First, it -checks if an opened s2s connection from the domain of the packet's -source to the domain of the packet's destination exists. If that is the case, -the s2s manager routes the packet to the process -serving this connection, otherwise a new connection is opened.
    -
    - - -

    6.2  Clustering Setup

    - - - -Suppose you already configured ejabberd on one machine named (first), -and you need to setup another one to make an ejabberd cluster. Then do -following steps: -
    1. -Copy ~ejabberd/.erlang.cookie file from first to - second.
      -
      -(alt) You can also add “-cookie content_of_.erlang.cookie” - option to all “erl” commands below.
      -
      -
    2. On second run as the `ejabberd' user in the directory - where ejabberd will work later the following command: -
      -erl -sname ejabberd \
-    -mnesia extra_db_nodes "['ejabberd@first']" \
-    -s mnesia
-
      - This will start Mnesia serving the same database as ejabberd@first. - You can check this by running the command “mnesia:info().”. You - should see a lot of remote tables and a line like the following: -
      -running db nodes   = [ejabberd@first, ejabberd@second]
-

      -
      -
    3. Now run the following in the same “erl” session: -
      -mnesia:change_table_copy_type(schema, node(), disc_copies).
-
      - This will create local disc storage for the database.
      -
      -(alt) Change storage type of `scheme' table to “RAM and disc - copy” on the second node via the web interface.
      -
      -
    4. Now you can add replicas of various tables to this node with - “mnesia:add_table_copy” or - “mnesia:change_table_copy_type” as above (just replace - “schema” with another table name and “disc_copies” - can be replaced with “ram_copies” or - “disc_only_copies”).
      -
      -Which tables to replicate is very dependant on your needs, you can get - some hints from the command “mnesia:info().”, by looking at the - size of tables and the default storage type for each table on 'first'.
      -
      -Replicating a table makes lookups in this table faster on this node. - Writing, on the other hand, will be slower. And of course if machine with one - of the replicas is down, other replicas will be used.
      -
      -Also section 5.3 (Table Fragmentation) of Mnesia User's Guide can be helpful. -
      -
      - (alt) Same as in previous item, but for other tables.
      -
      -
    5. Run “init:stop().” or just “q().” to exit from - the Erlang shell. This probably can take some time if Mnesia has not yet - transfered and processed all data it needed from first.
      -
      -
    6. Now run ejabberd on second with almost the same config as - on first (you probably don't need to duplicate “acl” - and “access” options — they will be taken from - first, and mod_muc and mod_irc should be - enabled only on one machine in the cluster). -
    -You can repeat these steps for other machines supposed to serve this -domain.
    -
    - - - -

    A  Built-in Modules

    - - - - - -

    A.1  Overview

    - - - -The following table lists all modules available in the official ejabberd -distribution. You can find more -contributed modules on the -ejabberd website. Please remember that these contributions might not work or -that they can contain severe bugs and security leaks. Therefore, use them at -your own risk!
    -
    -You can see which database backend each module needs by looking at the suffix: -
    • -“_ldap”, this means that the module needs an LDAP server as backend. -
    • “_odbc”, this means that the module needs an ODBC compatible database, - a MySQL database, or a PostgreSQL database as backend. -
    • Nothing, this means that the modules uses Erlang's built-in database - Mnesia as backend. -
    @@ -1465,7 +1604,7 @@ You can see which database backend each module needs by looking at the suffix: - + @@ -1491,19 +1630,9 @@ You can see which database backend each module needs by looking at the suffix: - + - - - - - - - - - - @@ -1521,19 +1650,9 @@ You can see which database backend each module needs by looking at the suffix: - + - - - - - - - - - - @@ -1557,22 +1676,12 @@ You can see which database backend each module needs by looking at the suffix: - + - - - - - - - - - - - - + + @@ -1611,39 +1720,31 @@ You can see which database backend each module needs by looking at the suffix: - + - - - - - - - - - -
    ModuleNo
     configuration of ejabberdconfiguration of ejabberd    
    mod_last_odbc Last Activity (JEP-0012)ODBC compatiblesupported database (*) No
      database, MySQL 
      or PostgreSQL 
    mod_muc Multi-User Chat (JEP-0045)  
    mod_offline_odbc Offline message storageODBC compatiblesupported database (*) No
      database, MySQL 
      or PostgreSQL 
    mod_privacy Blocking Communication  
    mod_roster Roster management  Yes (*)Yes (**)
    mod_roster_odbc Roster managementODBC compatibleYes (*)
      database, MySQL 
      or PostgreSQL supported database (*)Yes (**)
    mod_service_log Copy user messages to logger service
    mod_vcard_odbc vcard-temp (JEP-0054)ODBC compatiblesupported database (*) No
      database, MySQL 
      or PostgreSQL 
    mod_version Software Version (JEP-0092)   No
    -(*) This module or a similar one with another database backend is needed for -XMPP compliancy.
    -
    +
    • +(*) For a list of supported databases, see section 4. +
    • (**) This module or a similar one with another database backend is needed for +XMPP compliancy. +
    -

    A.2  Common Options

    +

    5.2  Common Options

    - + The following options are used by many modules. Therefore, they are described in this separate section.

    -

    A.2.1  iqdisc

    +

    5.2.1  iqdisc

    @@ -1677,7 +1778,7 @@ Example: -

    A.2.2  hosts

    +

    5.2.2  hosts

    @@ -1695,7 +1796,7 @@ Serving the echo module on one domain: {mod_echo, [{hosts, ["echo.example.org"]}]}, ... ]}. -
  • Backwards compatibility with older ejabberd versions can be retained +
  • Backwards compatibility with older ejabberd versions can be retained with: 
       {modules,
@@ -1716,7 +1817,7 @@ Serving the echo module on one domain:
    -

    A.3  mod_announce

    +

    5.3  mod_announce

    @@ -1732,7 +1833,7 @@ hosts: to several resources, only the resource with the highest priority will receive the message. If the registered user is not connected, the message will be stored offline in assumption that offline storage - (see section A.10) is enabled. + (see section 5.10) is enabled.
    example.org/announce/online (example.org/announce/all-hosts/online)
    The message is sent to all connected users. If the user is online and connected to several resources, all resources will receive the message. @@ -1782,7 +1883,7 @@ Only administrators can send announcements: -

    A.4  mod_disco

    +

    5.4  mod_disco

    @@ -1799,7 +1900,7 @@ Options: iqdisc
    This specifies the processing discipline for Service Discovery (http://jabber.org/protocol/disco#items and http://jabber.org/protocol/disco#info) IQ queries -(see section A.2.1). +(see section 5.2.1).
    extra_domains
    With this option, extra domains can be added to the Service Discovery item list. @@ -1834,7 +1935,7 @@ To serve a link to the Jabber User Directory on jabber.org: -

    A.5  mod_echo

    +

    5.5  mod_echo

    @@ -1846,8 +1947,8 @@ Options:
    hosts
    This option defines the hostnames of the - service (see section A.2.2). If neither hosts nor - the old host is present, the prefix “echo.” is added to all + service (see section 5.2.2). If neither hosts nor + the old host is present, the prefix `echo.' is added to all ejabberd hostnames.
    @@ -1863,11 +1964,11 @@ Mirror, mirror, on the wall, who is the most beautiful ... ]}.
  • If you still do not understand the inner workings of mod_echo, - you can find a few more examples in section A.2.2. + you can find a few more examples in section 5.2.2. -

    A.6  mod_irc

    +

    5.6  mod_irc

    @@ -1877,16 +1978,16 @@ servers.
    End user information:
    • -A Jabber client with “groupchat 1.0” support or Multi-User +A Jabber client with `groupchat 1.0' support or Multi-User Chat support (JEP-0045) is necessary to join IRC channels.
    • An IRC channel can be joined in nearly the same way as joining a Jabber Multi-User Chat room. The difference is that the room name will - be “channel%irc.example.org” in case irc.example.org is - the IRC server hosting “channel”. And of course the host should point + be `channel%irc.example.org' in case irc.example.org is + the IRC server hosting `channel'. And of course the host should point to the IRC transport instead of the Multi-User Chat service. -
    • You can register your nickame by sending “IDENTIFY password” to
      +
    • You can register your nickame by sending `IDENTIFY password' to
      nickserver!irc.example.org@irc.jabberserver.org. -
    • Entering your password is possible by sending “LOGIN nick password”
      +
    • Entering your password is possible by sending `LOGIN nick password'
      to nickserver!irc.example.org@irc.jabberserver.org.
    • When using a popular Jabber server, it can occur that no connection can be achieved with some IRC servers because they limit the @@ -1896,8 +1997,8 @@ Options:
      hosts
      This option defines the hostnames of the - service (see section A.2.2). If neither hosts nor - the old host is present, the prefix “irc.” is added to all + service (see section 5.2.2). If neither hosts nor + the old host is present, the prefix `irc.' is added to all ejabberd hostnames.
      access
      This option can be used to specify who @@ -1906,7 +2007,7 @@ Options: Examples:
      • In the first example, the IRC transport is available on (all) your - virtual host(s) with the prefix “irc.”. Furthermore, anyone is + virtual host(s) with the prefix `irc.'. Furthermore, anyone is able to use the transport. 
           {modules,
@@ -1937,7 +2038,7 @@ In the first example, the IRC transport is available on (all) your
      -

      A.7  mod_last

      +

      5.7  mod_last

      @@ -1950,11 +2051,11 @@ Options:
      iqdisc
      This specifies the processing discipline for Last activity (jabber:iq:last) IQ queries -(see section A.2.1). +(see section 5.2.1).
      -

      A.8  mod_muc

      +

      5.8  mod_muc

      @@ -1974,8 +2075,8 @@ Options:
      hosts
      This option defines the hostnames of the - service (see section A.2.2). If neither hosts nor - the old host is present, the prefix “conference.” is added to all + service (see section 5.2.2). If neither hosts nor + the old host is present, the prefix `conference.' is added to all ejabberd hostnames.
      access
      You can specify who is allowed to use @@ -1988,14 +2089,14 @@ Options: value is none, which means that only the room creator can administer his room). By sending a message to the service JID, administrators can send service messages that will be displayed in every - active room.
      -
      -
      history_size
      a small history of the - current discussion is send to users when they enter the room. This option make - it possible to define the number of history messages to keep and send to the - user joining the room. The value is a integer. Setting the value to 0 - disable the history feature and nothing is kept in memory. The default value - is 20. This value is global and affects all MUC rooms on the server. + active room. +
      history_size
      A small history of the + current discussion is sent to users when they enter the room. With this option + you can define the number of history messages to keep and send to users + joining the room. The value is an integer. Setting the value to 0 + disables the history feature and, as a result, nothing is kept in memory. The + default value is 20. This value is global and thus affects all rooms on + the server.
      Examples:
      • @@ -2003,9 +2104,9 @@ In the first example everyone is allowed to use the Multi-User Chat service. Everyone will also be able to create new rooms but only the user admin@example.org is allowed to administrate any room. In this example he is also a global administrator. When admin@example.org - sends a message such as “Tomorrow, the Jabber server will be moved + sends a message such as `Tomorrow, the Jabber server will be moved to new hardware. This will involve service breakdowns around 23:00 UMT. - We apologise for this inconvenience.” to conference.example.org, + We apologise for this inconvenience.' to conference.example.org, it will be displayed in all active rooms. In this example the history feature is disabled. 
        @@ -2026,9 +2127,9 @@ In the first example everyone is allowed to use the Multi-User Chat
  paying customers registered on our domains and on other servers. Of course
  the administrator is also allowed to access rooms. In addition, he is the
  only authority able to create and administer rooms. When
- admin@example.org sends a message such as “Tomorrow, the Jabber
+ admin@example.org sends a message such as `Tomorrow, the Jabber
  server will be moved to new hardware. This will involve service breakdowns
- around 23:00 UMT. We apologise for this inconvenience.” to
+ around 23:00 UMT. We apologise for this inconvenience.' to
  conference.example.org, it will be displayed in all active rooms. No
  history_size option is used, this means that the feature is enabled
  and the default value of 20 history messages will be send to the users.
@@ -2055,62 +2156,77 @@ In the first example everyone is allowed to use the Multi-User Chat
      -

      A.9  mod_muc_log

      +

      5.9  mod_muc_log

      -This module enables optional logging of Multi-User Chat conversations to HTML. -Once you enable this module, join a chatroom with enought privileges using a MUC capable Jabber client, -request the configuration form and there you will have an option to enable chatroom logging.
      +This module enables optional logging of Multi-User Chat (MUC) conversations to +HTML. Once you enable this module, users can join a chatroom using a MUC capable +Jabber client, and if they have enough privileges, they can request the +configuration form in which they can set the option to enable chatroom logging.

      -Some of the features of generated logs: +Features:
      • -A lot of information about chatroom is added on top of the page: Room title, JID, subject author, subject and configuration. -
      • Room title and JID are links to join the chatroom (using XMPP-IRI). +Chatroom details are added on top of each page: room title, JID, + author, subject and configuration. +
      • + Room title and JID are links to join the chatroom (using + XMPP URIs).
      • Subject and chatroom configuration changes are tracked and displayed. -
      • Joins, leaves, nick changes, kicks, bans and /me are tracked and displayed, including the reason when available. +
      • Joins, leaves, nick changes, kicks, bans and `/me' are tracked and + displayed, including the reason if available.
      • Generated HTML files are XHTML 1.0 Transitional and CSS compliant.
      • Timestamps are self-referencing links.
      • Links on top for quicker navigation: Previous day, Next day, Up.
      • CSS is used for style definition, and a custom CSS file can be used.
      • URLs on messages and subjects are converted to hyperlinks.
      • Timezone used on timestamps is shown on the log files. -
      • A custom link can be added on top of page. +
      • A custom link can be added on top of each page.
      Options:
      access_log
      - Restricts which users are allowed to enable or disable chatroom logging using ACL and ACCESS. - Default: muc_admin. - If you want to allow any chatroom owner put: muc. + This option restricts which users are allowed to enable or disable chatroom + logging. The default value is muc_admin. Note for this default setting + you need to have an access rule for muc_admin in order to take effect.
      cssfile
      - If HTMLs will use a custom CSS file or the embedded one. - Allowed values: - false: HTMLs will include the standard CSS code; - "CSS-URL": the URL of the CSS file (for example: "http://example.com/my.css"). - Default: false. + With this option you can set whether the HTML files should have a custom CSS + file or if they need to use the embedded CSS file. Allowed values are + false and an URL to a CSS file. With the first value, HTML files will + include the embedded CSS code. With the latter, you can specify the URL of the + custom CSS file (for example: `http://example.com/my.css'). The default value + is false.
      dirtype
      - Type of directory that will be created. - Allowed values: - subdirs: creates subdirectories for year and month; - plain: the filename contains the full date, no subdirs. - Default: subdirs. + The type of the created directories can be specified with this option. Allowed + values are subdirs and plain. With the first value, + subdirectories are created for each year and month. With the latter, the + names of the log files contain the full date, and there are no subdirectories. + The default value is subdirs.
      outdir
      - Full path to the directory where html will be generated. - Make sure the system user has write access on that directory. - Default: "www/muc". + This option sets the full path to the directory in which the HTML files should + be stored. Make sure the ejabberd daemon user has write access on that + directory. The default value is "www/muc".
      timezone
      - What timezone should be used. - Allowed values: - local: use local time, as reported to Erlang by the operating system; - universal: use GMT/UTC time. - Default: local. + The time zone for the logs is configurable with this option. Allowed values + are local and universal. With the first value, the local time, + as reported to Erlang by the operating system, will be used. With the latter, + GMT/UTC time will be used. The default value is local.
      top_link
      - Customizable link on top right corner. Syntax of this option: {"URL", "Text"}. - Default: {"/", "Home"}. + With this option you can customize the link on the top right corner of each + log file. The syntax of this option is {"URL", "Text"}. The default + value is {"/", "Home"}.
      -Example configuration: -
      +Examples:
+
      • 
+In the first example any chatroom owner can enable logging, and a
+ custom CSS file will be used (http://example.com/my.css). Further, the names
+ of the log files will contain the full date, and there will be no
+ subdirectories. The log files will be stored in /var/www/muclogs, and the
+ time zone will be GMT/UTC. Finally, the top link will be
+ <a href="http://www.jabber.ru">Jabber.ru</a>.
+ 
        +  {access, muc, [{allow, all}]}.
+  ...
   {modules,
    [
     ...
@@ -2124,10 +2240,35 @@ Example configuration:
     ]},
     ...
    ]}.
-
        
+
    • In the second example only admin1@example.org and + admin2@example.net can enable logging, and the embedded CSS file will be + used. Further, the names of the log files will only contain the day (number), + and there will be subdirectories for each year and month. The log files will + be stored in /var/www/muclogs, and the local time will be used. Finally, the + top link will be the default <a href="/">Home</a>. + 
      +  {acl, admins, {user, "admin1", "example.org"}}.
+  {acl, admins, {user, "admin2", "example.net"}}.
+  ...
+  {access, muc_log, [{allow, admins},
+                     {deny, all}]}.
+  ...
+  {modules,
+   [
+    ...
+    {mod_muc_log, [
+               {access_log, muc_log},
+               {cssfile, false},
+               {dirtype, subdirs},
+               {outdir, "/var/www/muclogs"},
+               {timezone, local}
+    ]},
+    ...
+   ]}.
+
    -

    A.10  mod_offline

    +

    5.10  mod_offline

    @@ -2135,11 +2276,11 @@ This module implements offline message storage. This means that all messages sent to an offline user will be stored on the server until that user comes online again. Thus it is very similar to how email works. Note that ejabberdctl has a command to delete expired messages -(see section 3.4.2).
    +(see section 7.2).

    -

    A.11  mod_privacy

    +

    5.11  mod_privacy

    @@ -2148,19 +2289,19 @@ as defined in section 10 from XMPP IM. If end users have support for it in their Jabber client, they will be able to:
    • -Retrieving one's privacy lists. -
    • Adding, removing, and editing one's privacy lists. -
    • Setting, changing, or declining active lists. +Retrieving one's privacy lists. +
    • Adding, removing, and editing one's privacy lists. +
    • Setting, changing, or declining active lists.
    • Setting, changing, or declining the default list (i.e., the list that - is active by default). + is active by default).
    • Allowing or blocking messages based on JID, group, or subscription type - (or globally). + (or globally).
    • Allowing or blocking inbound presence notifications based on JID, group, - or subscription type (or globally). + or subscription type (or globally).
    • Allowing or blocking outbound presence notifications based on JID, group, - or subscription type (or globally). + or subscription type (or globally).
    • Allowing or blocking IQ stanzas based on JID, group, or subscription type - (or globally). + (or globally).
    • Allowing or blocking all communications based on JID, group, or subscription type (or globally).
    @@ -2170,11 +2311,11 @@ Options:
    iqdisc
    This specifies the processing discipline for Blocking Communication (jabber:iq:privacy) IQ queries -(see section A.2.1). +(see section 5.2.1).
    -

    A.12  mod_private

    +

    5.12  mod_private

    @@ -2189,11 +2330,11 @@ Options:
    iqdisc
    This specifies the processing discipline for Private XML Storage (jabber:iq:private) IQ queries -(see section A.2.1). +(see section 5.2.1).
    -

    A.13  mod_pubsub

    +

    5.13  mod_pubsub

    @@ -2223,16 +2364,15 @@ Options:
    hosts
    This option defines the hostnames of the - service (see section A.2.2). If neither hosts nor - the old host is present, the prefix “pubsub.” is added to all + service (see section 5.2.2). If neither hosts nor + the old host is present, the prefix `pubsub.' is added to all ejabberd hostnames.
    served_hosts
    To specify which hosts needs to be served, you can use this option. If absent, only the main ejabberd host is served.
    access_createnode
    - Restricts which users are allowed to create pubsub nodes using ACL and ACCESS. - Default: pubsub_createnode. -
    + This option restricts which users are allowed to create pubsub nodes using + ACL and ACCESS. The default value is pubsub_createnode. Example: 
       {modules,
@@ -2246,7 +2386,7 @@ Example:
    -

    A.14  mod_register

    +

    5.14  mod_register

    @@ -2260,12 +2400,12 @@ Register a new account on the server. Options:
    access
    This option can be configured to specify - rules to restrict registration. If a rule returns “deny” on the requested + rules to restrict registration. If a rule returns `deny' on the requested user name, registration for that user name is dennied. (there are no restrictions by default).
    iqdisc
    This specifies the processing discipline for In-Band Registration (jabber:iq:register) IQ queries -(see section A.2.1). +(see section 5.2.1).
    Examples:
    • @@ -2302,7 +2442,7 @@ Next example prohibits the registration of too short account names:
    -

    A.15  mod_roster

    +

    5.15  mod_roster

    @@ -2312,11 +2452,11 @@ Options:
    iqdisc
    This specifies the processing discipline for Roster Management (jabber:iq:roster) IQ queries -(see section A.2.1). +(see section 5.2.1).
    -

    A.16  mod_service_log

    +

    5.16  mod_service_log

    @@ -2356,7 +2496,7 @@ To log all end user packets to the Bandersnatch service running on -

    A.17  mod_shared_roster

    +

    5.17  mod_shared_roster

    @@ -2370,7 +2510,7 @@ Shared roster groups can be edited only via the web interface. Each gro has a unique identification and the following parameters:
    Name
    The name of the group, which will be displayed in the roster. -
    Description
    The description of the group. This parameter doesn't affect +
    Description
    The description of the group. This parameter does not affect anything.
    Members
    A list of full JIDs of group members, entered one per line in the web interface. @@ -2483,7 +2623,7 @@ Take the case of a computer club that wants all its members seeing each -

    A.18  mod_stats

    +

    5.18  mod_stats

    @@ -2499,7 +2639,7 @@ Options:
    iqdisc
    This specifies the processing discipline for Statistics Gathering (http://jabber.org/protocol/stats) IQ queries -(see section A.2.1). +(see section 5.2.1).
    As there are only a small amount of clients (for example Tkabber) and software libraries with @@ -2525,7 +2665,7 @@ You can request the number of online users on the current virtual host -

    A.19  mod_time

    +

    5.19  mod_time

    @@ -2536,11 +2676,11 @@ Options:
    iqdisc
    This specifies the processing discipline for Entity Time (jabber:iq:time) IQ queries -(see section A.2.1). +(see section 5.2.1).
    -

    A.20  mod_vcard

    +

    5.20  mod_vcard

    @@ -2553,29 +2693,28 @@ Options:
    hosts
    This option defines the hostnames of the - service (see section A.2.2). If neither hosts nor - the old host is present, the prefix “vjud.” is added to all + service (see section 5.2.2). If neither hosts nor + the old host is present, the prefix `vjud.' is added to all ejabberd hostnames.
    iqdisc
    This specifies the processing discipline for vcard-temp IQ queries -(see section A.2.1). -
    search
    This option specifies whether the search - functionality is enabled (value: true) or disabled - (value: false). If disabled, the option hosts will be - ignored and the Jabber User Directory service will not appear in the - Service Discovery item list. The default value is true. -
    matches
    With this option, the number of reported +(see section 5.2.1). +
    search
    This option specifies whether the search + functionality is enabled (value: true) or disabled (value: + false). If disabled, the option hosts will be ignored and the + Jabber User Directory service will not appear in the Service Discovery item + list. The default value is true. +
    matches
    With this option, the number of reported search results can be limited. If the option's value is set to infinity, all search results are reported. The default value is 30. -
    allow_return_all
    This option enables - you to specify if search operations with empty input fields should return - all users who added some information to their vCard. The default value is +
    allow_return_all
    This option enables + you to specify if search operations with empty input fields should return all + users who added some information to their vCard. The default value is false. -
    search_all_hosts
    If this option is - set to true, search operations will apply to all virtual hosts. - Otherwise only the current host will be searched. The default value is - true. +
    search_all_hosts
    If this option is set + to true, search operations will apply to all virtual hosts. Otherwise + only the current host will be searched. The default value is true.
    Examples:
    • @@ -2604,124 +2743,51 @@ In this first situation, search results are limited to twenty items, ... ]}.
    - + -

    A.21  LDAP and mod_vcard_ldap

    - - - - - -

    A.21.1  Features

    - - -ejabberd has built-in LDAP support. You can authenticate users against LDAP -server and use LDAP directory as vCard storage. Shared rosters are not -supported yet.
    -
    - - -

    A.21.2  Connection

    - - -Parameters: -
    -ldap_server
    IP address or dns name of your -LDAP server. This option is required. -
    ldap_port
    Port to connect to LDAP server. -Default is 389. -
    ldap_rootdn
    Bind DN. Default is "" -which means anonymous connection. -
    ldap_password
    Bind password. Default -is "". -
    -Example: -
    -  {auth_method, ldap}.
-  {ldap_servers, ["ldap.mydomain.org"]}.
-  {ldap_port, 389}.
-  {ldap_rootdn, "cn=Manager,dc=domain,dc=org"}.
-  {ldap_password, "secret"}.
-
    -Note that current LDAP implementation doesn't support SSL connection and SASL -authentication.
    -
    - - -

    A.21.3  Authentication

    - - -You can authenticate users against LDAP directory. Available parameters are -listed below: -
    -ldap_base
    LDAP base directory which stores users -accounts. This option is required. -
    ldap_uidattr
    LDAP attribute which holds -user's part of JID. Default is "uid". -
    ldap_uidattr_format
    Format of the -ldap_uidattr variable. Format MUST contain one and only one pattern -variable "%u" which will be replaced by user's part of JID. For example, -"%u@mydomain.org". Default value is "%u". -
    ldap_filter
    RFC 2254 LDAP filter. Default is -none. Example: "(&(objectClass=shadowAccount)(memberOf=Jabber - Users))". Please, don't forget closing brackets and don't use superfluous -whitespaces. Also you MUST NOT use ldap_uidattr attribute in filter -because this attribute will be substituted in LDAP filter automatically. -
    - - -

    A.21.4  vCards and Search

    +

    5.21  mod_vcard_ldap

    + ejabberd can map LDAP attributes to vCard fields. This behaviour is -implemented in mod_vcard_ldap module. This module doesn't depend on -authentication method. mod_vcard_ldap module has it's own optional -parameters. The first group of parameters has the same meaning as top-level -LDAP parameters: ldap_servers, ldap_port, -ldap_rootdn, ldap_password, ldap_base, -ldap_uidattr, ldap_uidattr_format and -ldap_filter. If one of this option is not set ejabberd will look -for top-level option with the same name. The second group of parameters -consists of the following options: +implemented in the mod_vcard_ldap module. This module does not depend on the +authentication method (see 4.5.2). The mod_vcard_ldap module +has its own optional parameters. The first group of parameters has the same +meaning as the top-level LDAP parameters to set the authentication method: +ldap_servers, ldap_port, ldap_rootdn, +ldap_password, ldap_base, ldap_uidattr, +ldap_uidattr_format and ldap_filter. See +section 4.5.2 for detailed information about these options. If one +of these options is not set, ejabberd will look for the top-level option with +the same name. The second group of parameters consists of the following +mod_vcard_ldap-specific options:
    hosts
    This option defines the hostnames of the - service (see section A.2.2). If neither hosts nor - the old host is present, the prefix “vjud.” is added to all + service (see section 5.2.2). If neither hosts nor + the old host is present, the prefix `vjud.' is added to all ejabberd hostnames.
    iqdisc
    This specifies the processing discipline for vcard-temp IQ queries -(see section A.2.1). -
    search
    This option specifies whether the search - functionality is enabled (value: true) or disabled - (value: false). If disabled, the option hosts will be - ignored and the Jabber User Directory service will not appear in the - Service Discovery item list. The default value is true. -
    ldap_vcard_map
    the table which defines -reflection of LDAP attributes to vCard fields. - Format is: - [Name_of_vcard_field, Pattern, List_of_LDAP_attributes, ...] - where - Name_of_vcard_field is the type name of vCard as defined - in RFC 2426, - Pattern is a string which contains pattern variables "%u", "%d" or "%s", - List_of_LDAP_attributes is the list which contains of LDAP attributes. - Pattern variables "%s" will be sequentially replaced with the values of - LDAP attributes from List_of_LDAP_attributes; "%u" will be replaced with - user's part of JID and "%d" will be replaced with domain part of JID. - Example: -
    -  {ldap_vcard_map,
-   [{"NICKNAME", "%u", []},
-    {"FN", "%s", ["displayName"]},
-    {"CTRY", "Russia", []},
-    {"EMAIL", "%u@%d", []},
-    {"DESC", "%s\n%s", ["title", "description"]}
-   ]},
-
    -Default is: -
    +(see section 5.2.1).
+
    search
    This option specifies whether the search
+ functionality is enabled (value: true) or disabled (value:
+ false). If disabled, the option hosts will be ignored and the
+ Jabber User Directory service will not appear in the Service Discovery item
+ list. The default value is true.
+
    ldap_vcard_map
    With this option you can
+ set the table that maps LDAP attributes to vCard fields. The format is:
+ [Name_of_vCard_field, Pattern, List_of_LDAP_attributes, ...].
+ Name_of_vcard_field is the type name of the vCard as defined in
+ RFC 2426. Pattern is a
+ string which contains pattern variables "%u", "%d" or
+ "%s". List_of_LDAP_attributes is the list containing LDAP
+ attributes. The pattern variables "%s" will be sequentially replaced
+ with the values of LDAP attributes from List_of_LDAP_attributes,
+ "%u" will be replaced with the user part of a JID, and "%d"
+ will be replaced with the domain part of a JID. The default is:
+ 
       [{"NICKNAME", "%u", []},
    {"FN", "%s", ["displayName"]},
    {"FAMILY", "%s", ["sn"]},
@@ -2742,25 +2808,13 @@ Default is:
    {"BDAY", "%s", ["birthDay"]},
    {"ROLE", "%s", ["employeeType"]},
    {"PHOTO", "%s", ["jpegPhoto"]}]
-
    ldap_search_fields
     This option defines
-search form and LDAP attributes to search.
-	Format:
-		[Name, Attribute, ...]
-	where
-		Name is the name of field in the search form. Will be automatically
-			translated according to definitions in translation files (see
-			msgs/*.msg for available words).
-		Attribute is the LDAP attribute or the pattern "%u"
- Example:
-
    -  {ldap_search_fields,
-   [{"User", "uid"},
-    {"Full Name", "displayName"},
-    {"Email", "mail"}
-   ]},
-
    
-Default is:
-
    +
    ldap_search_fields
    This option
+ defines the search form and the LDAP attributes to search within. The format
+ is: [Name, Attribute, ...]. Name is the name of a search form
+ field which will be automatically translated by using the translation
+ files (see msgs/*.msg for available words). Attribute is the
+ LDAP attribute or the pattern "%u". The default is:
+ 
       [{"User", "%u"},
    {"Full Name", "displayName"},
    {"Given Name", "givenName"},
@@ -2773,24 +2827,13 @@ Default is:
    {"Email", "mail"},
    {"Organization Name", "o"},
    {"Organization Unit", "ou"}]
-
    ldap_search_reported
     This option defines search fields to be reported.
-	Format:
-		[Name, VCard_Name, ...]
-	where
-		Name is the name of field in the search form. Will be automatically
-			translated according to definitions in translation files (see
-			msgs/*.msg for available words).
-		VCard_Name is the name of vCard field defined in ldap_vcard_map option.
- Example:
-
    -  {ldap_search_reported,
-   [{"Full Name", "FN"},
-    {"Email", "EMAIL"},
-    {"Birthday", "BDAY"},
-    {"Nickname", "NICKNAME"}
-   ]},
-
    
-Default is:
+
    ldap_search_reported
    This option + defines which search fields should be reported. The format is: + [Name, vCard_Name, ...]. Name is the name of a search form + field which will be automatically translated by using the translation + files (see msgs/*.msg for available words). vCard_Name is the + vCard field name defined in the ldap_vcard_map option. The default + is: 
       [{"Full Name", "FN"},
    {"Given Name", "GIVEN"},
@@ -2804,30 +2847,20 @@ Default is:
    {"Organization Name", "ORGNAME"},
    {"Organization Unit", "ORGUNIT"}]
    - - -

    A.21.5  Examples

    - - - - -
    Common example
    - -Let's say ldap.mydomain.org is the name of our LDAP server. We have -users with their passwords in "ou=Users,dc=mydomain,dc=org" directory. +Examples: +
    • +
      +
      +Let's say ldap.example.org is the name of our LDAP server. We have +users with their passwords in "ou=Users,dc=example,dc=org" directory. Also we have addressbook, which contains users emails and their additional -infos in "ou=AddressBook,dc=mydomain,dc=org" directory. Corresponding +infos in "ou=AddressBook,dc=example,dc=org" directory. Corresponding authentication section should looks like this: 
         %% authentication method
   {auth_method, ldap}.
   %% DNS name of our LDAP server
-  {ldap_servers, ["ldap.mydomain.org"]}.
-  %% Bind to LDAP server as "cn=Manager,dc=mydomain,dc=org" with password "secret"
-  {ldap_rootdn, "cn=Manager,dc=mydomain,dc=org"}.
-  {ldap_password, "secret"}.
-  %% define the user's base
-  {ldap_base, "ou=Users,dc=mydomain,dc=org"}.
+  {ldap_servers, ["ldap.example.org"]}.
   %% We want to authorize users from 'shadowAccount' object class only
   {ldap_filter, "(objectClass=shadowAccount)"}.
      @@ -2842,16 +2875,16 @@ Also we want users to search each other. Let's see how we can set it up: [ %% We use the same server and port, but want to bind anonymously because %% our LDAP server accepts anonymous requests to - %% "ou=AddressBook,dc=mydomain,dc=org" subtree. + %% "ou=AddressBook,dc=example,dc=org" subtree. {ldap_rootdn, ""}, {ldap_password, ""}, %% define the addressbook's base - {ldap_base, "ou=AddressBook,dc=mydomain,dc=org"}, + {ldap_base, "ou=AddressBook,dc=example,dc=org"}, %% user's part of JID is located in the "mail" attribute {ldap_uidattr, "mail"}, %% common format for our emails - {ldap_uidattr_format, "%u@mail.mydomain.org"}, - %% We have to define empty filter here, because entries in addressbook doesn't + {ldap_uidattr_format, "%u@mail.example.org"}, + %% We have to define empty filter here, because entries in addressbook does not %% belong to shadowAccount object class {ldap_filter, ""}, %% Now we want to define vCard pattern @@ -2882,60 +2915,34 @@ Also we want users to search each other. Let's see how we can set it up: Note that mod_vcard_ldap module checks an existence of the user before searching his info in LDAP.

      - - -
      Active Directory
      - -Active Directory is just an LDAP-server with predefined attributes. Sample -config file is listed below: +
    • ldap_vcard_map example: 
      -  {auth_method, ldap}.
-  {ldap_servers, ["office.org"]}.    % List of LDAP servers
-  {ldap_base, "DC=office,DC=org"}. % Search base of LDAP directory
-  {ldap_rootdn, "CN=Administrator,CN=Users,DC=office,DC=org"}. % LDAP manager
-  {ldap_password, "*******"}. % Password to LDAP manager
-  {ldap_uidattr, "sAMAccountName"}.
-  {ldap_filter, "(memberOf=*)"}.
-  
-  {mod_vcard_ldap,
-   [{ldap_vcard_map,
-     [{"NICKNAME", "%u", []},
-      {"GIVEN", "%s", ["givenName"]},
-      {"MIDDLE", "%s", ["initials"]},
-      {"FAMILY", "%s", ["sn"]},
-      {"FN", "%s", ["displayName"]},
-      {"EMAIL", "%s", ["mail"]},
-      {"ORGNAME", "%s", ["company"]},
-      {"ORGUNIT", "%s", ["department"]},
-      {"CTRY", "%s", ["c"]},
-      {"LOCALITY", "%s", ["l"]},
-      {"STREET", "%s", ["streetAddress"]},
-      {"REGION", "%s", ["st"]},
-      {"PCODE", "%s", ["postalCode"]},
-      {"TITLE", "%s", ["title"]},
-      {"URL", "%s", ["wWWHomePage"]},
-      {"DESC", "%s", ["description"]},
-      {"TEL", "%s", ["telephoneNumber"]}]},
-    {ldap_search_fields,
-     [{"User", "%u"},
-      {"Name", "givenName"},
-      {"Family Name", "sn"},
-      {"Email", "mail"},
-      {"Company", "company"},
-      {"Department", "department"},
-      {"Role", "title"},
-      {"Description", "description"},
-      {"Phone", "telephoneNumber"}]},
-    {ldap_search_reported,
-     [{"Full Name", "FN"},
-      {"Nickname", "NICKNAME"},
-      {"Email", "EMAIL"}]}
-   ]
-  }.
-
      + {ldap_vcard_map, + [{"NICKNAME", "%u", []}, + {"FN", "%s", ["displayName"]}, + {"CTRY", "Russia", []}, + {"EMAIL", "%u@%d", []}, + {"DESC", "%s\n%s", ["title", "description"]} + ]}, +
    • ldap_search_fields example: +
      +  {ldap_search_fields,
+   [{"User", "uid"},
+    {"Full Name", "displayName"},
+    {"Email", "mail"}
+   ]},
+
    • ldap_search_reported example: +
      +  {ldap_search_reported,
+   [{"Full Name", "FN"},
+    {"Email", "EMAIL"},
+    {"Birthday", "BDAY"},
+    {"Nickname", "NICKNAME"}
+   ]},
+
    -

    A.22  mod_version

    +

    5.22  mod_version

    @@ -2946,11 +2953,355 @@ Options:
    iqdisc
    This specifies the processing discipline for Software Version (jabber:iq:version) IQ queries -(see section A.2.1). +(see section 5.2.1).
    + + +

    6  Creating an Initial Administrator

    + + +Before the web interface can be entered to perform administration tasks, an +account with administrator rights is needed on your ejabberd deployment.
    +
    +Instructions to create an initial administrator account: +
    1. +Register an account on your ejabberd deployment. An account can be + created in two ways: +
      1. + Using the tool ejabberdctl (see + section 7.2): + 
        +% ejabberdctl node@host register admin example.org password
+
      2. Using In-Band Registration (see section 5.14): you can + use a Jabber client to register an account. +
      +
    2. Edit the configuration file to promote the account created in the previous + step to an account with administrator rights. Note that if you want to add + more administrators, a seperate acl entry is needed for each administrator. + 
      +  {acl, admins, {user, "admin", "example.org"}}.
+  {access, configure, [{allow, admins}]}.
+
    3. Restart ejabberd to load the new configuration. +
    4. Open the web interface (http://server:port/admin/) in your + favourite browser. Make sure to enter the full JID as username (in this + example: admin@example.org. The reason that you also need to enter the + suffix, is because ejabberd's virtual hosting support. +
    + + +

    7  Online Configuration and Monitoring

    + + + + +

    7.1  Web Interface

    + + + +To perform online configuration of ejabberd you need to enable the +ejabberd_http listener with the option web_admin (see +section 3.3). Then you can open +http://server:port/admin/ in your favourite web browser. You +will be asked to enter the username (the full Jabber ID) and password +of an ejabberd user with administrator rights. After authentication +you will see a page similar to figure 1. +
    + + webadmmain.png + + +
    +
    +
    Figure 1: Top page from the web interface

    +
    + + +
    +Here you can edit access restrictions, manage users, create backups, +manage the database, enable/disable ports listened for, view server +statistics,...
    +
    +Examples: +
    • +You can serve the web interface on the same port as the + HTTP Polling interface. In this example + you should point your web browser to http://example.org:5280/admin/ to + administer all virtual hosts or to + http://example.org:5280/admin/server/example.com/ to administer only + the virtual host example.com. Before you get access to the web interface + you need to enter as username, the JID and password from a registered user + that is allowed to configure ejabberd. In this example you can enter as + username `admin@example.net' to administer all virtual hosts (first + URL). If you log in with `admin@example.com' on
      +http://example.org:5280/admin/server/example.com/ you can only + administer the virtual host example.com. + 
      +  ...
+  {acl, admins, {user, "admin", "example.net"}}.
+  {host_config, "example.com", [{acl, admins, {user, "admin", "example.com"}}]}.
+  {access, configure, [{allow, admins}]}.
+  ...
+  {hosts, ["example.org"]}.
+  ...
+  {listen,
+   [...
+    {5280, ejabberd_http, [http_poll, web_admin]},
+    ...
+   ]
+  }.
+
    • For security reasons, you can serve the web interface on a secured + connection, on a port differing from the HTTP Polling interface, and bind it + to the internal LAN IP. The web interface will be accessible by pointing your + web browser to https://192.168.1.1:5280/admin/: + 
      +  ...
+  {hosts, ["example.org"]}.
+  ...
+  {listen,
+   [...
+    {5270, ejabberd_http,    [http_poll]},
+    {5280, ejabberd_http,    [web_admin, {ip, {192, 168, 1, 1}},
+                              tls, {certfile, "/usr/local/etc/server.pem"}]},
+    ...
+   ]
+  }.
+
    + + +

    7.2  ejabberdctl

    + + + +It is possible to do some administration operations using the command +line tool ejabberdctl. You can list all available options by +running ejabberdctl without arguments: +
    +% ejabberdctl
+Usage: ejabberdctl node command
+
+Available commands:
+  status                        get ejabberd status
+  stop                          stop ejabberd
+  restart                       restart ejabberd
+  reopen-log                    reopen log file
+  register user server password register a user
+  unregister user server        unregister a user
+  backup file                   store a database backup to file
+  restore file                  restore a database backup from file
+  install-fallback file         install a database fallback from file
+  dump file                     dump a database to a text file
+  load file                     restore a database from a text file
+  import-file file              import user data from jabberd 1.4 spool file
+  import-dir dir                import user data from jabberd 1.4 spool directory
+  registered-users              list all registered users
+  delete-expired-messages       delete expired offline messages from database
+
+Example:
+  ejabberdctl ejabberd@host restart
+
    +Additional information: +
    +reopen-log
    If you use a tool to rotate logs, you have to configure it + so that this command is executed after each rotation. +
    backup, restore, install-fallback, dump, load
    You can use these + commands to create and restore backups. +
    import-file, import-dir
    + These options can be used to migrate from other Jabber/XMPP servers. There + exist tutorials to migrate from other software to ejabberd. +
    delete-expired-messages
    This option can be used to delete old messages + in offline storage. This might be useful when the number of offline messages + is very high. +
    + + +

    8  Firewall Settings

    + + + +You need to take the following TCP ports in mind when configuring your firewall: +
    + + + + + + + + + + + + + + + + + + +
    PortDescription
    5222SASL and unencrypted c2s connections.
    5223Obsolete SSL c2s connections.
    5269s2s connections.
    4369Only for clustering (see 10).
    port rangeOnly for clustring (see 10). This range + is configurable (see 2.4).
    +
    + + +

    9  SRV Records

    + + + + + + +

    10  Clustering

    + + + + + +

    10.1  How it Works

    + + + +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 ~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...
    +
    +Each ejabberd node has the following modules: +
    • +router, +
    • local router, +
    • session manager, +
    • s2s manager. +
    + + +

    10.1.1  Router

    + + + +This module is the main router of Jabber packets on each node. It +routes them based on their destination's domains. It uses a global +routing table. The domain of the packet's destination is searched in the +routing table, and if it is found, the packet is routed to the +appropriate process. If not, it is sent to the s2s manager.
    +
    + + +

    10.1.2  Local Router

    + + + +This module routes packets which have a destination domain equal to +one of this server's host names. If the destination JID has a non-empty user +part, it is routed to the session manager, otherwise it is processed depending +on its content.
    +
    + + +

    10.1.3  Session Manager

    + + + +This module routes packets to local users. It looks up to which user +resource a packet must be sent via a presence table. Then the packet is +either routed to the appropriate c2s process, or stored in offline +storage, or bounced back.
    +
    + + +

    10.1.4  s2s Manager

    + + + +This module routes packets to other Jabber servers. First, it +checks if an opened s2s connection from the domain of the packet's +source to the domain of the packet's destination exists. If that is the case, +the s2s manager routes the packet to the process +serving this connection, otherwise a new connection is opened.
    +
    + + +

    10.2  Clustering Setup

    + + + +Suppose you already configured ejabberd on one machine named (first), +and you need to setup another one to make an ejabberd cluster. Then do +following steps: +
    1. +Copy ~ejabberd/.erlang.cookie file from first to + second.
      +
      +(alt) You can also add `-cookie content_of_.erlang.cookie' + option to all `erl' commands below.
      +
      +
    2. On second run the following command as the ejabberd daemon user, + in the working directory of ejabberd: +
      +erl -sname ejabberd \
+    -mnesia extra_db_nodes "['ejabberd@first']" \
+    -s mnesia
+
      + This will start Mnesia serving the same database as ejabberd@first. + You can check this by running the command `mnesia:info().'. You + should see a lot of remote tables and a line like the following: +
      +running db nodes   = [ejabberd@first, ejabberd@second]
+

      +
      +
    3. Now run the following in the same `erl' session: +
      +mnesia:change_table_copy_type(schema, node(), disc_copies).
+
      + This will create local disc storage for the database.
      +
      +(alt) Change storage type of the scheme table to `RAM and disc + copy' on the second node via the web interface.
      +
      +
    4. Now you can add replicas of various tables to this node with + `mnesia:add_table_copy' or + `mnesia:change_table_copy_type' as above (just replace + `schema' with another table name and `disc_copies' + can be replaced with `ram_copies' or + `disc_only_copies').
      +
      +Which tables to replicate is very dependant on your needs, you can get + some hints from the command `mnesia:info().', by looking at the + size of tables and the default storage type for each table on 'first'.
      +
      +Replicating a table makes lookups in this table faster on this node. + Writing, on the other hand, will be slower. And of course if machine with one + of the replicas is down, other replicas will be used.
      +
      +Also section 5.3 (Table Fragmentation) of Mnesia User's Guide can be helpful. +
      +
      + (alt) Same as in previous item, but for other tables.
      +
      +
    5. Run `init:stop().' or just `q().' to exit from + the Erlang shell. This probably can take some time if Mnesia has not yet + transfered and processed all data it needed from first.
      +
      +
    6. Now run ejabberd on second with almost the same config as + on first (you probably do not need to duplicate `acl' + and `access' options — they will be taken from + first, and mod_muc and mod_irc should be + enabled only on one machine in the cluster). +
    +You can repeat these steps for other machines supposed to serve this +domain.
    +
    + -

    B  Internationalization and Localization

    +

    A  Internationalization and Localization

    @@ -2966,7 +3317,7 @@ Figure 2, for example, shows the reply to the f
    - + discorus.png
    @@ -2980,26 +3331,26 @@ The web interface also supports the Accept-Language HTTP header (co figure 3 with figure 1)
    - + webadmmainru.png

    Figure 3: Top page from the web interface with HTTP header - “Accept-Language: ru”

    + `Accept-Language: ru'


    -

    C  Release Notes

    +

    B  Release Notes

    -

    C.1  ejabberd 0.9

    +

    B.1  ejabberd 0.9

            Release notes
@@ -3093,7 +3444,7 @@ Bugfixes
    -

    C.2  ejabberd 0.9.1

    +

    B.2  ejabberd 0.9.1

            Release notes
@@ -3161,7 +3512,7 @@ Bugfixes
    -

    C.3  ejabberd 0.9.8

    +

    B.3  ejabberd 0.9.8

            Release notes
@@ -3266,7 +3617,7 @@ END
    -

    C.4  ejabberd 1.0.0

    +

    B.4  ejabberd 1.0.0

            Release Notes
@@ -3392,7 +3743,7 @@ END
    -

    C.5  ejabberd 1.1.0

    +

    B.5  ejabberd 1.1.0

         Release Notes
@@ -3513,7 +3864,7 @@ END
    -

    C.6  ejabberd 1.1.1

    +

    B.6  ejabberd 1.1.1

         Release Notes
@@ -3638,13 +3989,14 @@ END
    -

    D  Acknowledgements

    +

    C  Acknowledgements

    - Thanks to all people who contributed to this guide: + + +

    D  Copyright Information

    + + +Ejabberd Installation and Operation Guide.
    +Copyright © January 23, 2003 — Alexey Shchepin
    +
    +This document is free software; you can redistribute it and/or +modify it under the terms of the GNU General Public License +as published by the Free Software Foundation; either version 2 +of the License, or (at your option) any later version.
    +
    +This document is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details.
    +
    +You should have received a copy of the GNU General Public License along with +this document; if not, write to the Free Software Foundation, Inc., 51 Franklin +Street, Fifth Floor, Boston, MA 02110-1301, USA.
    +
    diff --git a/doc/guide.tex b/doc/guide.tex index c9443da5c..468f7143d 100644 --- a/doc/guide.tex +++ b/doc/guide.tex @@ -78,10 +78,15 @@ the processing discipline for #1 IQ queries \newcommand{\hostitem}[1]{ \titem{hosts} \ind{options!hosts} This option defines the hostnames of the service (see section~\ref{sec:modhostsoption}). If neither \texttt{hosts} nor - the old \texttt{host} is present, the prefix ``\jid{#1.}'' is added to all + the old \texttt{host} is present, the prefix `\jid{#1.}' is added to all \ejabberd{} hostnames. } +%\newcommand{\quoting}[2][yozhik]{\begin{quotation}\textcolor{#1}{\textit{#2}}\end{quotation}} % Quotes enabled +%\renewcommand{command}[args][default]{def} +%\renewcommand{\headrule}{{\color{ejblue}% +%\hrule width\headwidth height\headrulewidth \vskip-\headrulewidth}} + %% Title page \include{version} \title{Ejabberd \version\ Installation and Operation Guide} @@ -92,9 +97,11 @@ the processing discipline for #1 IQ queries %% Options \newcommand{\marking}[1]{#1} % Marking disabled \newcommand{\quoting}[2][yozhik]{} % Quotes disabled -\newcommand{\new}{\begin{latexonly}\marginpar{\textsc{new}}\end{latexonly}} % Highlight new features -\newcommand{\improved}{\begin{latexonly}\marginpar{\textsc{improved}}\end{latexonly}} % Highlight improved features -\newcommand{\moreinfo}[1]{} % Hide details +\newcommand{\new}{\marginpar{\textsc{new}}} % Highlight new features +\newcommand{\improved}{\marginpar{\textsc{improved}}} % Highlight improved features + +%% To by-pass errors in the HTML version. +\newstyle{SPAN}{width:20\%; float:right; text-align:left; margin-left:auto;} %% Footnotes \begin{latexonly} @@ -108,7 +115,7 @@ the processing discipline for #1 IQ queries \begin{document} -\label{sec:titlepage} +\label{titlepage} \begin{titlepage} \maketitle{} @@ -118,7 +125,7 @@ the processing discipline for #1 IQ queries } \end{center} - \begin{quotation}\textit{I can thoroughly recommend ejabberd for ease of setup -- + \begin{quotation}\textit{I can thoroughly recommend ejabberd for ease of setup --- Kevin Smith, Current maintainer of the Psi project}\end{quotation} \end{titlepage} @@ -135,31 +142,30 @@ the processing discipline for #1 IQ queries % Input introduction.tex \input{introduction} -\section{Installation from Source} -\label{sec:installation} +\section{\aname{installsource}{Installation from Source}} +\label{sec:installsource} \ind{installation} -\subsection{Installation Requirements} +\subsection{\aname{installreq}{Installation Requirements}} \label{sec:installreq} +\ind{installation!requirements} -\subsubsection{``Unix-like'' operating systems} +\subsubsection{\aname{installrequnix}{`Unix-like' operating systems}} \label{sec:installrequnix} -\ind{installation!requirements for ``Unix-like'' operating systems} -To compile \ejabberd{} on a ``Unix-like'' operating system, you need: +To compile \ejabberd{} on a `Unix-like' operating system, you need: \begin{itemize} -\item GNU Make; -\item GCC; -\item libexpat 1.95 or higher; -\item Erlang/OTP R9C-2 or higher; -\item OpenSSL 0.9.6 or higher (optional). -\item Zlib 1.2.3 or higher (optional). -\item GNU Iconv 1.8 or higher (optional, not needed at all on systems with GNU libc). +\item GNU Make +\item GCC +\item libexpat 1.95 or higher +\item Erlang/OTP R9C-2 or higher +\item OpenSSL 0.9.6 or higher (optional) +\item Zlib 1.2.3 or higher (optional) +\item GNU Iconv 1.8 or higher (optional, not needed on systems with GNU libc) \end{itemize} -\subsubsection{Windows} +\subsubsection{\aname{installreqwin}{Windows}} \label{sec:installreqwin} -\ind{installation!requirements for Windows} To compile \ejabberd{} on a Windows flavour, you need: \begin{itemize} @@ -174,7 +180,7 @@ To compile \ejabberd{} on a Windows flavour, you need: \item \footahref{http://www.zlib.net/}{Zlib 1.2.3 or higher} \end{itemize} -\subsection{Obtaining \ejabberd{}} +\subsection{\aname{obtaining}{Obtaining \ejabberd{}}} \label{sec:obtaining} \ind{download} @@ -187,15 +193,14 @@ The latest development version can be retrieved from the Subversion repository\@ svn co http://svn.process-one.net/ejabberd/trunk ejabberd \end{verbatim} -\subsection{Compilation} -\label{sec:compilation} -\ind{compilation} +\subsection{\aname{compile}{Compilation}} +\label{sec:compile} +\ind{installation!compilation} -\subsubsection{``Unix-like'' operating systems} -\label{sec:compilationunix} -\ind{compilation!on ``Unix-like'' operating systems} +\subsubsection{\aname{compileunix}{`Unix-like' operating systems}} +\label{sec:compileunix} -Compile \ejabberd{} on a ``Unix-like'' operating system by executing: +Compile \ejabberd{} on a `Unix-like' operating system by executing: \begin{verbatim} ./configure @@ -211,9 +216,12 @@ These commands will: \item create a directory called \verb|/var/log/ejabberd| to store log files. \end{itemize} -\subsubsection{Windows} -\label{sec:compilationwin} -\ind{compilation!on Windows} +Note: if you want to use an external database, you need to execute the configure +script with the option(s) \term{--enable-odbc} or \term{--enable-odbc +--enable-mssql}. See section~\ref{sec:database} for more information. + +\subsubsection{\aname{compilewin}{Windows}} +\label{sec:compilewin} \begin{itemize} \item Install Erlang emulator (for example, into \verb|C:\Program Files\erl5.3|). @@ -246,9 +254,12 @@ werl -s ejabberd -name ejabberd \end{verbatim} \end{itemize} -\subsection{Starting} -\label{sec:starting} +%TODO: how to compile database support on windows? + +\subsection{\aname{start}{Starting}} +\label{sec:start} \ind{starting} +%TODO: update when the ejabberdctl script is made more userfriendly Execute the following command to start \ejabberd{}: \begin{verbatim} @@ -259,7 +270,7 @@ or erl -pa /var/lib/ejabberd/ebin -sname ejabberd -s ejabberd \end{verbatim} In the latter case the Erlang node will be identified using only the first part -of the host name, i.\,e. other Erlang nodes outside this domain can't contact +of the host name, i.\,e. other Erlang nodes outside this domain cannot contact this node. Note that when using the above command, \ejabberd{} will search for the @@ -297,11 +308,8 @@ To reduce memory usage, you may set the environment variable But in this case \ejabberd{} can start to work slower. -\section{Configuration} -\label{sec:configuration} - -\subsection{Initial Configuration} -\label{sec:initconfig} +\section{\aname{basicconfig}{Basic Configuration}} +\label{sec:basicconfig} \ind{configuration file} The configuration file will be loaded the first time you start \ejabberd{}. The @@ -311,7 +319,7 @@ configuration file are appended to the entries in the database. The configuration file contains a sequence of Erlang terms. Lines beginning with a \term{`\%'} sign are ignored. Each term is a tuple of which the first element is the name of an option, and any further elements are that option's values. If the -configuration file do not contain for instance the ``hosts'' option, the old +configuration file do not contain for instance the `hosts' option, the old host name(s) stored in the database will be used. @@ -325,8 +333,8 @@ the configuration file: With these lines the old global options, local options and ACLs will be removed before new ones are added. -\subsubsection{Host Names} -\label{sec:confighostname} +\subsection{\aname{hostnames}{Host Names}} +\label{sec:hostnames} \ind{options!hosts}\ind{host names} The option \option{hosts} defines a list containing one or more domains that @@ -335,46 +343,382 @@ The option \option{hosts} defines a list containing one or more domains that Examples: \begin{itemize} \item Serving one domain: -\begin{itemize} -\item \begin{verbatim} + \begin{verbatim} {hosts, ["example.org"]}. \end{verbatim} -\item Backwards compatibility with older \ejabberd{} versions can be retained - with: +\item Serving one domain, and backwards compatible with older \ejabberd{} + versions: \begin{verbatim} {host, "example.org"}. \end{verbatim} -\end{itemize} \item Serving two domains: \begin{verbatim} {hosts, ["example.net", "example.com"]}. \end{verbatim} \end{itemize} -\subsubsection{Default Language} -\label{sec:configlanguage} -\ind{options!language}\ind{language} +\subsection{\aname{virtualhost}{Virtual Hosting}} +\label{sec:virtualhost} +\ind{virtual hosting}\ind{virtual hosts}\ind{virtual domains} -The option \option{language} defines the default language of server strings that -can be seen by \Jabber{} clients. If a \Jabber{} client do not support -\option{xml:lang}, the specified language is used. The default value for the -option \option{language} is \term{"en"}. In order to take effect there must be a -translation file \term{.msg} in \ejabberd{}'s \term{msgs} directory. +Options can be defined separately for every virtual host using the +\term{host\_config} option.\ind{options!host\_config} It has the following +syntax: +\begin{verbatim} + {host_config, , [