diff options
| author | Mickaël Rémond <mickael.remond@process-one.net> | 2005-11-28 13:55:45 +0300 |
|---|---|---|
| committer | Mickaël Rémond <mickael.remond@process-one.net> | 2005-11-28 13:55:45 +0300 |
| commit | f89f62167124ab7e92eba22942a3fd812bea9e01 (patch) | |
| tree | 23ae2b95b0c60db763eb996e3d4867a460d66a1d /doc | |
| parent | 53ddd788ef164f7da24ca7853b6245515c896ad8 (diff) | |
Documentation update
SVN Revision: 445
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/guide.html | 2590 | ||||
| -rw-r--r-- | doc/guide.tex | 1822 | ||||
| -rw-r--r-- | doc/introduction.tex | 131 | ||||
| -rw-r--r-- | doc/logo.png | bin | 19917 -> 83054 bytes | |||
| -rw-r--r-- | doc/version.tex | 2 |
5 files changed, 3126 insertions, 1419 deletions
diff --git a/doc/guide.html b/doc/guide.html index 06f9025d2..7a08f9078 100644 --- a/doc/guide.html +++ b/doc/guide.html @@ -1,278 +1,386 @@ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd"> <HTML> -<HEAD><TITLE>Ejabberd Installation and Operation Guide</TITLE> -<META http-equiv="Content-Type" content="text/html; charset=ISO8859-1"> -<META name="GENERATOR" content="hevea 1.07"> +<HEAD> + +<TITLE>Ejabberd 0.9.9-alpha Installation and Operation Guide</TITLE> + +<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<META name="GENERATOR" content="hevea 1.08"> +<STYLE type="text/css"> +.toc{list-style:none;} +.title{margin:auto;text-align:center} +.center{text-align:center;margin-left:auto;margin-right:auto;} +.flushleft{text-align:left;margin-left:0ex;margin-right:auto;} +.flushright{text-align:right;margin-left:auto;margin-right:0ex;} +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} +</STYLE> </HEAD> + <BODY > -<!--HEVEA command line is: /usr/bin/hevea -charset ISO8859-1 guide.tex --> +<!--HEVEA command line is: hevea guide.tex --> <!--HTMLHEAD--> <!--ENDHTML--> <!--PREFIX <ARG ></ARG>--> <!--CUT DEF section 1 --> +<BR> +<BR> +<A NAME="sec:titlepage"></A> - -<H1 ALIGN=center>Ejabberd Installation and Operation Guide</H1> - -<H3 ALIGN=center>Alexey Shchepin<BR> + <TABLE CLASS="title"> +<TR><TD> +<H1 CLASS="titlemain">Ejabberd 0.9.9-alpha Installation and Operation Guide</H1> +<H3 CLASS="titlerest">Alexey Shchepin<BR> <A HREF="mailto:alexey@sevcom.net"><TT>mailto:alexey@sevcom.net</TT></A><BR> -<A HREF="xmpp:aleksey@jabber.ru"><TT>xmpp:aleksey@jabber.ru</TT></A></H3> - -<H3 ALIGN=center>July 31, 2005</H3><DIV ALIGN=center> - +<A HREF="xmpp:aleksey@jabber.ru"><TT>xmpp:aleksey@jabber.ru</TT></A></H3></TD> +</TR></TABLE><BR> +<BR> +<DIV CLASS="center"> + <IMG SRC="logo.png"> - </DIV><BR> + <BR> <BR> + </DIV> +<BLOCKQUOTE CLASS="quotation"><I>I can thoroughly recommend ejabberd for ease of setup – + Kevin Smith, Current maintainer of the Psi project</I></BLOCKQUOTE> +<!--TOC section Contents--> -<!--TOC section Table of Contents--> +<H2 CLASS="section">Contents</H2><!--SEC END --> -<H2>Table of Contents</H2><!--SEC END --> - -<UL><LI> +<UL CLASS="toc"><LI CLASS="li-toc"> <A HREF="#htoc1">1 Introduction</A> -<LI><A HREF="#htoc2">2 Installation from Source</A> -<UL><LI> -<A HREF="#htoc3">2.1 Installation Requirements</A> -<UL><LI> -<A HREF="#htoc4">2.1.1 Unix</A> -<LI><A HREF="#htoc5">2.1.2 Windows</A> +<UL CLASS="toc"><LI CLASS="li-toc"> +<A HREF="#htoc2">1.1 Key Features</A> +<LI CLASS="li-toc"><A HREF="#htoc3">1.2 Additional Features</A> +</UL> +<LI CLASS="li-toc"><A HREF="#htoc4">2 Installation from Source</A> +<UL CLASS="toc"><LI CLASS="li-toc"> +<A HREF="#htoc5">2.1 Installation Requirements</A> +<UL CLASS="toc"><LI CLASS="li-toc"> +<A HREF="#htoc6">2.1.1 “Unix-like” operating systems</A> +<LI CLASS="li-toc"><A HREF="#htoc7">2.1.2 Windows</A> +</UL> +<LI CLASS="li-toc"><A HREF="#htoc8">2.2 Obtaining <TT>ejabberd</TT></A> +<LI CLASS="li-toc"><A HREF="#htoc9">2.3 Compilation</A> +<UL CLASS="toc"><LI CLASS="li-toc"> +<A HREF="#htoc10">2.3.1 “Unix-like” operating systems</A> +<LI CLASS="li-toc"><A HREF="#htoc11">2.3.2 Windows</A> </UL> -<LI><A HREF="#htoc6">2.2 Obtaining</A> -<LI><A HREF="#htoc7">2.3 Compilation</A> -<UL><LI> -<A HREF="#htoc8">2.3.1 Unix</A> -<LI><A HREF="#htoc9">2.3.2 Windows</A> +<LI CLASS="li-toc"><A HREF="#htoc12">2.4 Starting</A> </UL> -<LI><A HREF="#htoc10">2.4 Starting</A> +<LI CLASS="li-toc"><A HREF="#htoc13">3 Configuration</A> +<UL CLASS="toc"><LI CLASS="li-toc"> +<A HREF="#htoc14">3.1 Initial Configuration</A> +<UL CLASS="toc"><LI CLASS="li-toc"> +<A HREF="#htoc15">3.1.1 Host Names</A> +<LI CLASS="li-toc"><A HREF="#htoc16">3.1.2 Default Language</A> +<LI CLASS="li-toc"><A HREF="#htoc17">3.1.3 Access Rules</A> +<LI CLASS="li-toc"><A HREF="#htoc18">3.1.4 Shapers</A> +<LI CLASS="li-toc"><A HREF="#htoc19">3.1.5 Listened Sockets</A> +<LI CLASS="li-toc"><A HREF="#htoc20">3.1.6 Modules</A> +<LI CLASS="li-toc"><A HREF="#htoc21">3.1.7 Virtual Hosting</A> </UL> -<LI><A HREF="#htoc11">3 Configuration</A> -<UL><LI> -<A HREF="#htoc12">3.1 Initial Configuration</A> -<UL><LI> -<A HREF="#htoc13">3.1.1 Host Names</A> -<LI><A HREF="#htoc14">3.1.2 Default Language</A> -<LI><A HREF="#htoc15">3.1.3 Access Rules</A> -<LI><A HREF="#htoc16">3.1.4 Shapers Configuration</A> -<LI><A HREF="#htoc17">3.1.5 Listened Sockets</A> -<LI><A HREF="#htoc18">3.1.6 Modules</A> -<LI><A HREF="#htoc19">3.1.7 Virtual Host Configuration</A> +<LI CLASS="li-toc"><A HREF="#htoc22">3.2 Creating an Initial Administrator</A> +<LI CLASS="li-toc"><A HREF="#htoc23">3.3 Online Configuration and Monitoring</A> +<UL CLASS="toc"><LI CLASS="li-toc"> +<A HREF="#htoc24">3.3.1 Web Interface</A> +<LI CLASS="li-toc"><A HREF="#htoc25">3.3.2 <TT>ejabberdctl</TT></A> </UL> -<LI><A HREF="#htoc20">3.2 Online Configuration and Monitoring</A> -<UL><LI> -<A HREF="#htoc21">3.2.1 Web-based Administration Interface</A> -<LI><A HREF="#htoc22">3.2.2 <TT>ejabberdctl</TT> tool</A> </UL> +<LI CLASS="li-toc"><A HREF="#htoc26">4 Firewall Settings</A> +<LI CLASS="li-toc"><A HREF="#htoc27">5 SRV Records</A> +<LI CLASS="li-toc"><A HREF="#htoc28">6 Clustering</A> +<UL CLASS="toc"><LI CLASS="li-toc"> +<A HREF="#htoc29">6.1 How it Works</A> +<UL CLASS="toc"><LI CLASS="li-toc"> +<A HREF="#htoc30">6.1.1 Router</A> +<LI CLASS="li-toc"><A HREF="#htoc31">6.1.2 Local Router</A> +<LI CLASS="li-toc"><A HREF="#htoc32">6.1.3 Session Manager</A> +<LI CLASS="li-toc"><A HREF="#htoc33">6.1.4 s2s Manager</A> </UL> -<LI><A HREF="#htoc23">4 Clustering</A> -<UL><LI> -<A HREF="#htoc24">4.1 How it works</A> -<UL><LI> -<A HREF="#htoc25">4.1.1 Router</A> -<LI><A HREF="#htoc26">4.1.2 Local Router</A> -<LI><A HREF="#htoc27">4.1.3 Session Manager</A> -<LI><A HREF="#htoc28">4.1.4 S2S Manager</A> +<LI CLASS="li-toc"><A HREF="#htoc34">6.2 Clustering Setup</A> </UL> -<LI><A HREF="#htoc29">4.2 How to setup ejabberd cluster</A> +<LI CLASS="li-toc"><A HREF="#htoc35">A Built-in Modules</A> +<UL CLASS="toc"><LI CLASS="li-toc"> +<A HREF="#htoc36">A.1 Common Options</A> +<UL CLASS="toc"><LI CLASS="li-toc"> +<A HREF="#htoc37">A.1.1 <TT>iqdisc</TT></A> +<LI CLASS="li-toc"><A HREF="#htoc38">A.1.2 <TT>hosts</TT></A> </UL> -<LI><A HREF="#htoc30">A Built-in Modules</A> -<UL><LI> -<A HREF="#htoc31">A.1 Common Options</A> -<UL><LI> -<A HREF="#htoc32">A.1.1 <TT>iqdisc</TT></A> -<LI><A HREF="#htoc33">A.1.2 <TT>host</TT></A> -<LI><A HREF="#htoc34">A.1.3 <TT>hosts</TT></A> +<LI CLASS="li-toc"><A HREF="#htoc39">A.2 <TT>mod_announce</TT></A> +<LI CLASS="li-toc"><A HREF="#htoc40">A.3 <TT>mod_disco</TT></A> +<LI CLASS="li-toc"><A HREF="#htoc41">A.4 <TT>mod_echo</TT></A> +<LI CLASS="li-toc"><A HREF="#htoc42">A.5 <TT>mod_irc</TT></A> +<LI CLASS="li-toc"><A HREF="#htoc43">A.6 <TT>mod_last</TT></A> +<LI CLASS="li-toc"><A HREF="#htoc44">A.7 <TT>mod_muc</TT></A> +<LI CLASS="li-toc"><A HREF="#htoc45">A.8 <TT>mod_offline</TT></A> +<LI CLASS="li-toc"><A HREF="#htoc46">A.9 <TT>mod_privacy</TT></A> +<LI CLASS="li-toc"><A HREF="#htoc47">A.10 <TT>mod_private</TT></A> +<LI CLASS="li-toc"><A HREF="#htoc48">A.11 <TT>mod_pubsub</TT></A> +<LI CLASS="li-toc"><A HREF="#htoc49">A.12 <TT>mod_register</TT></A> +<LI CLASS="li-toc"><A HREF="#htoc50">A.13 <TT>mod_roster</TT></A> +<LI CLASS="li-toc"><A HREF="#htoc51">A.14 <TT>mod_service_log</TT></A> +<LI CLASS="li-toc"><A HREF="#htoc52">A.15 <TT>mod_shared_roster</TT></A> +<LI CLASS="li-toc"><A HREF="#htoc53">A.16 <TT>mod_stats</TT></A> +<LI CLASS="li-toc"><A HREF="#htoc54">A.17 <TT>mod_time</TT></A> +<LI CLASS="li-toc"><A HREF="#htoc55">A.18 <TT>mod_vcard</TT></A> +<LI CLASS="li-toc"><A HREF="#htoc56">A.19 <TT>mod_version</TT></A> </UL> -<LI><A HREF="#htoc35">A.2 <TT>mod_announce</TT></A> -<LI><A HREF="#htoc36">A.3 <TT>mod_configure</TT></A> -<LI><A HREF="#htoc37">A.4 <TT>mod_disco</TT></A> -<LI><A HREF="#htoc38">A.5 <TT>mod_echo</TT></A> -<LI><A HREF="#htoc39">A.6 <TT>mod_irc</TT></A> -<LI><A HREF="#htoc40">A.7 <TT>mod_last</TT></A> -<LI><A HREF="#htoc41">A.8 <TT>mod_muc</TT></A> -<LI><A HREF="#htoc42">A.9 <TT>mod_offline</TT></A> -<LI><A HREF="#htoc43">A.10 <TT>mod_privacy</TT></A> -<LI><A HREF="#htoc44">A.11 <TT>mod_private</TT></A> -<LI><A HREF="#htoc45">A.12 <TT>mod_pubsub</TT></A> -<LI><A HREF="#htoc46">A.13 <TT>mod_register</TT></A> -<LI><A HREF="#htoc47">A.14 <TT>mod_roster</TT></A> -<LI><A HREF="#htoc48">A.15 <TT>mod_service_log</TT></A> -<LI><A HREF="#htoc49">A.16 <TT>mod_shared_roster</TT></A> -<LI><A HREF="#htoc50">A.17 <TT>mod_stats</TT></A> -<LI><A HREF="#htoc51">A.18 <TT>mod_time</TT></A> -<LI><A HREF="#htoc52">A.19 <TT>mod_vcard</TT></A> -<LI><A HREF="#htoc53">A.20 <TT>mod_version</TT></A> +<LI CLASS="li-toc"><A HREF="#htoc57">B Internationalization and Localization</A> +<LI CLASS="li-toc"><A HREF="#htoc58">C Release Notes</A> +<UL CLASS="toc"><LI CLASS="li-toc"> +<A HREF="#htoc59">C.1 ejabberd 0.9</A> +<LI CLASS="li-toc"><A HREF="#htoc60">C.2 ejabberd 0.9.1</A> +<LI CLASS="li-toc"><A HREF="#htoc61">C.3 ejabberd 0.9.8</A> </UL> -<LI><A HREF="#htoc54">B I18n/L10n</A> +<LI CLASS="li-toc"><A HREF="#htoc62">D Acknowledgements</A> </UL> <!--TOC section Introduction--> -<H2><A NAME="htoc1">1</A> Introduction</H2><!--SEC END --> - -<A NAME="sec:intro"></A> -<TT>ejabberd</TT> is a Free and Open Source fault-tolerant distributed Jabber -server. It is written mostly in Erlang.<BR> -<BR> -The main features of <TT>ejabberd</TT> are: -<UL><LI> -Works on most of popular platforms: *nix (tested on Linux, FreeBSD and - NetBSD) and Win32 -<LI>Distributed: You can run <TT>ejabberd</TT> on a cluster of machines to let all of - them serve one Jabber domain. -<LI>Fault-tolerance: You can setup an <TT>ejabberd</TT> cluster so that all the - information required for a properly working service will be stored - permanently on more than one node. This means that if one of the nodes - crashes, then the others will continue working without disruption. - You can also add or replace nodes ``on the fly''. -<LI>Support for virtual hosting -<LI>Built-in <A HREF="http://www.jabber.org/jeps/jep-0045.html">Multi-User Chat</A> service -<LI>Built-in IRC transport -<LI>Built-in <A HREF="http://www.jabber.org/jeps/jep-0060.html">Publish-Subscribe</A> service -<LI>Built-in Jabber Users Directory service based on users vCards -<LI>Built-in web-based administration interface -<LI>Built-in <A HREF="http://www.jabber.org/jeps/jep-0025.html">HTTP Polling</A> service -<LI>SSL support -<LI>Support for LDAP authentication -<LI>Ability to interface with external components (JIT, MSN-t, Yahoo-t, etc.) -<LI>Migration from jabberd14 is possible -<LI>Mostly XMPP-compliant -<LI>Support for <A HREF="http://www.jabber.org/jeps/jep-0030.html">Service Discovery</A>. -<LI>Support for <A HREF="http://www.jabber.org/jeps/jep-0039.html">Statistics Gathering</A>. -<LI>Support for <TT>xml:lang</TT> +<H2 CLASS="section"><A NAME="htoc1">1</A> Introduction</H2><!--SEC END --> + +<A NAME="sec:intr"></A> + +<TT>ejabberd</TT> is a free (GPL) distributed fault-tolerant Jabber/XMPP server and is mainly written in <A HREF="http://www.erlang.org/">Erlang</A>.<BR> +<BR> +<TT>ejabberd</TT> is designed to be a stable and feature rich Jabber/XMPP server.<BR> +<BR> +<TT>ejabberd</TT> is suitable for small servers, whether they need to be scalable or not, as well as extremely big servers.<BR> +<BR> +<!--TOC subsection Key Features--> + +<H3 CLASS="subsection"><A NAME="htoc2">1.1</A> Key Features</H3><!--SEC END --> + +<A NAME="sec:keyfeatures"></A> + +<TT>ejabberd</TT> is: +<UL CLASS="itemize"><LI CLASS="li-itemize"> +Multiplatform: <TT>ejabberd</TT> runs under Windows NT/2000/XP and Unix derived systems such as Linux, FreeBSD and NetBSD.<BR> +<BR> +<LI CLASS="li-itemize">Distributed: You can run <TT>ejabberd</TT> on a cluster of machines and all of them will serve one Jabber domain. 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 hundreds of concurrent users.<BR> +<BR> +<LI CLASS="li-itemize">Fault-tolerant: You can deploy an <TT>ejabberd</TT> 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”.<BR> +<BR> +<LI CLASS="li-itemize">Administrator Friendly: <TT>ejabberd</TT> 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 installed, and ready to run out of the box. Other benefits for administrators include: +<UL CLASS="itemize"><LI CLASS="li-itemize"> +Comprehensive documentation. +<LI CLASS="li-itemize">Straightforward installers for Windows and Linux. +<LI CLASS="li-itemize">Web interface for administration tasks. +<LI CLASS="li-itemize">Shared Roster groups. +<LI CLASS="li-itemize">Command line administration tool. +<LI CLASS="li-itemize">Can integrate with existing authentication mechanisms. +<LI CLASS="li-itemize">Capability to send announce messages. +<LI CLASS="li-itemize">Statistics via <A HREF="http://www.jabber.org/jeps/jep-0039.html">JEP-0039</A> (Statistics Gathering). +</UL><BR> +<BR> +<LI CLASS="li-itemize">Internationalized: <TT>ejabberd</TT> leads in internationalization. Hence it is very well suited in a globalized world. Related features are: +<UL CLASS="itemize"><LI CLASS="li-itemize"> +Translated in 11 languages. +<LI CLASS="li-itemize">Support for <A HREF="http://www.ietf.org/rfc/rfc3490.txt">IDNA</A>. +<LI CLASS="li-itemize">Support for <TT>xml:lang</TT>. +</UL><BR> +<BR> +<LI CLASS="li-itemize">Modular: <TT>ejabberd</TT>'s modular architecture allows easy customization: +<UL CLASS="itemize"><LI CLASS="li-itemize"> +Load only the modules you want. +<LI CLASS="li-itemize">Extend <TT>ejabberd</TT> with your own custom modules. +</UL></UL> +<!--TOC subsection Additional Features--> + +<H3 CLASS="subsection"><A NAME="htoc3">1.2</A> Additional Features</H3><!--SEC END --> + +<A NAME="sec:addfeatures"></A> + +Besides common Jabber server features, <TT>ejabberd</TT> comes with a wide range of other features: +<UL CLASS="itemize"><LI CLASS="li-itemize"> +The ability to interface via external components with networks such as: +<UL CLASS="itemize"><LI CLASS="li-itemize"> +AIM +<LI CLASS="li-itemize">ICQ +<LI CLASS="li-itemize">MSN +<LI CLASS="li-itemize">Yahoo! +</UL> +<LI CLASS="li-itemize">Open Standards +<UL CLASS="itemize"><LI CLASS="li-itemize"> +<A HREF="http://ejabberd.jabber.ru/protocols">Many JEPs supported</A>. +<LI CLASS="li-itemize">XML-based protocol +<LI CLASS="li-itemize">Fully XMPP compliant for c2s connections (Core & IM) +</UL> +<LI CLASS="li-itemize">Security +<UL CLASS="itemize"><LI CLASS="li-itemize"> +SASL and STARTTLS for c2s connections. +<LI CLASS="li-itemize">STARTTLS and Dialback s2s connections. +<LI CLASS="li-itemize">Obsolete SSL for c2s connections also supported. +<LI CLASS="li-itemize">Web interface accessible via HTTPS secure access. +</UL> +<LI CLASS="li-itemize">Databases +<UL CLASS="itemize"><LI CLASS="li-itemize"> +Mnesia. +<LI CLASS="li-itemize">ODBC data storage support (tested against PostgreSQL). +</UL> +<LI CLASS="li-itemize">Authentication +<UL CLASS="itemize"><LI CLASS="li-itemize"> +LDAP. +<LI CLASS="li-itemize">External Authentication script. +<LI CLASS="li-itemize">Internal Authentication. +</UL> +<LI CLASS="li-itemize">Others +<UL CLASS="itemize"><LI CLASS="li-itemize"> +IPv6 support both for c2s and s2s connections. +<LI CLASS="li-itemize">Support for virtual hosting. +<LI CLASS="li-itemize"><A HREF="http://www.jabber.org/jeps/jep-0025.html">HTTP Polling</A> service +<LI CLASS="li-itemize"><A HREF="http://www.jabber.org/jeps/jep-0045.html">Multi-User Chat</A> module. +<LI CLASS="li-itemize">IRC transport. +<LI CLASS="li-itemize"><A HREF="http://www.jabber.org/jeps/jep-0060.html">Publish-Subscribe</A> component. +<LI CLASS="li-itemize">Users Directory based on users vCards. </UL> -The misfeatures of <TT>ejabberd</TT> are: -<UL><LI> -No support for authentication and STARTTLS in S2S connections </UL> <!--TOC section Installation from Source--> -<H2><A NAME="htoc2">2</A> Installation from Source</H2><!--SEC END --> +<H2 CLASS="section"><A NAME="htoc4">2</A> Installation from Source</H2><!--SEC END --> <A NAME="sec:installation"></A> + <!--TOC subsection Installation Requirements--> -<H3><A NAME="htoc3">2.1</A> Installation Requirements</H3><!--SEC END --> +<H3 CLASS="subsection"><A NAME="htoc5">2.1</A> Installation Requirements</H3><!--SEC END --> <A NAME="sec:installreq"></A> -<!--TOC subsubsection Unix--> +<!--TOC subsubsection “Unix-like” operating systems--> -<H4><A NAME="htoc4">2.1.1</A> Unix</H4><!--SEC END --> +<H4 CLASS="subsubsection"><A NAME="htoc6">2.1.1</A> “Unix-like” operating systems</H4><!--SEC END --> <A NAME="sec:installrequnix"></A> -To compile <TT>ejabberd</TT>, you will need the following packages: -<UL><LI> + +To compile <TT>ejabberd</TT> on a “Unix-like” operating system, you need: +<UL CLASS="itemize"><LI CLASS="li-itemize"> GNU Make; -<LI>GCC; -<LI>libexpat 1.95 or later; -<LI>Erlang/OTP R8B or later; -<LI>OpenSSL 0.9.6 or later (optional). +<LI CLASS="li-itemize">GCC; +<LI CLASS="li-itemize">libexpat 1.95 or higher; +<LI CLASS="li-itemize">Erlang/OTP R8B or higher; +<LI CLASS="li-itemize">OpenSSL 0.9.6 or higher (optional). </UL> <!--TOC subsubsection Windows--> -<H4><A NAME="htoc5">2.1.2</A> Windows</H4><!--SEC END --> +<H4 CLASS="subsubsection"><A NAME="htoc7">2.1.2</A> Windows</H4><!--SEC END --> <A NAME="sec:installreqwin"></A> -To compile <TT>ejabberd</TT> in MS Windows environment, you will need the following -packages: -<UL><LI> + +To compile <TT>ejabberd</TT> on a Windows flavour, you need: +<UL CLASS="itemize"><LI CLASS="li-itemize"> MS Visual C++ 6.0 Compiler -<LI><A HREF="http://erlang.org/download/otp_win32_R10B-1a.exe">Erlang/OTP R10B-1a</A> -<LI><A HREF="http://prdownloads.sourceforge.net/expat/expat_win32bin_1_95_7.exe?download">Expat 1.95.7</A> -<LI><A HREF="http://ftp.gnu.org/pub/gnu/libiconv/libiconv-1.9.1.tar.gz">Iconv 1.9.1</A> +<LI CLASS="li-itemize"><A HREF="http://erlang.org/download.html">Erlang/OTP R8B or higher</A> +<LI CLASS="li-itemize"><A HREF="http://sourceforge.net/project/showfiles.php?group_id=10127&package_id=11277">Expat 1.95.7 or higher</A> +<LI CLASS="li-itemize"><A HREF="http://www.gnu.org/software/libiconv/">Iconv 1.9.1</A> (optional) -<LI><A HREF="http://www.slproweb.com/products/Win32OpenSSL.html">Shining Light OpenSSL</A> +<LI CLASS="li-itemize"><A HREF="http://www.slproweb.com/products/Win32OpenSSL.html">Shining Light OpenSSL</A> (to enable SSL connections) </UL> -<!--TOC subsection Obtaining--> +<!--TOC subsection Obtaining <TT>ejabberd</TT>--> -<H3><A NAME="htoc6">2.2</A> Obtaining</H3><!--SEC END --> +<H3 CLASS="subsection"><A NAME="htoc8">2.2</A> Obtaining <TT>ejabberd</TT></H3><!--SEC END --> <A NAME="sec:obtaining"></A> -Stable <TT>ejabberd</TT> release can be obtained at + +Released versions of <TT>ejabberd</TT> can be obtained from <BR> <A HREF="http://www.process-one.net/en/projects/ejabberd/download.html"><TT>http://www.process-one.net/en/projects/ejabberd/download.html</TT></A>.<BR> <BR> -The latest alpha version can be retrieved from Subversion repository. -<PRE> - svn co svn://svn.process-one.net/opt/data/svn/ejabberd/trunk ejabberd + +The latest development version can be retrieved from the Subversion repository. +<PRE CLASS="verbatim"> + svn co http://svn.process-one.net/ejabberd/trunk ejabberd </PRE> <!--TOC subsection Compilation--> -<H3><A NAME="htoc7">2.3</A> Compilation</H3><!--SEC END --> +<H3 CLASS="subsection"><A NAME="htoc9">2.3</A> Compilation</H3><!--SEC END --> <A NAME="sec:compilation"></A> -<!--TOC subsubsection Unix--> -<H4><A NAME="htoc8">2.3.1</A> Unix</H4><!--SEC END --> +<!--TOC subsubsection “Unix-like” operating systems--> + +<H4 CLASS="subsubsection"><A NAME="htoc10">2.3.1</A> “Unix-like” operating systems</H4><!--SEC END --> <A NAME="sec:compilationunix"></A> -<PRE> + +Compile <TT>ejabberd</TT> on a “Unix-like” operating system by executing: +<PRE CLASS="verbatim"> ./configure make su make install </PRE> -This will install <TT>ejabberd</TT> to <CODE>/var/lib/ejabberd</CODE> directory, -<CODE>ejabberd.cfg</CODE> to <CODE>/etc/ejabberd</CODE> directory and create -<CODE>/var/log/ejabberd</CODE> directory for log files.<BR> -<BR> +These commands will: +<UL CLASS="itemize"><LI CLASS="li-itemize"> +install <TT>ejabberd</TT> into the directory <CODE>/var/lib/ejabberd</CODE>, +<LI CLASS="li-itemize">install the configuration file into <CODE>/etc/ejabberd</CODE>, +<LI CLASS="li-itemize">create a directory called <CODE>/var/log/ejabberd</CODE> to store log files. +</UL> <!--TOC subsubsection Windows--> -<H4><A NAME="htoc9">2.3.2</A> Windows</H4><!--SEC END --> +<H4 CLASS="subsubsection"><A NAME="htoc11">2.3.2</A> Windows</H4><!--SEC END --> <A NAME="sec:compilationwin"></A> -<UL><LI> + +<UL CLASS="itemize"><LI CLASS="li-itemize"> Install Erlang emulator (for example, into <CODE>C:\Program Files\erl5.3</CODE>). -<LI>Install Expat library into <CODE>C:\Program Files\Expat-1.95.7</CODE> +<LI CLASS="li-itemize">Install Expat library into <CODE>C:\Program Files\Expat-1.95.7</CODE> directory.<BR> <BR> Copy file <CODE>C:\Program Files\Expat-1.95.7\Libs\libexpat.dll</CODE> to your Windows system directory (for example, <CODE>C:\WINNT</CODE> or <CODE>C:\WINNT\System32</CODE>) -<LI>Build and install Iconv library into <CODE>C:\Program Files\iconv-1.9.1</CODE> directory.<BR> +<LI CLASS="li-itemize">Build and install the Iconv library into the directory + <CODE>C:\Program Files\iconv-1.9.1</CODE>.<BR> <BR> Copy file <CODE>C:\Program Files\iconv-1.9.1\bin\iconv.dll</CODE> to your - Windows system directory.<BR> + Windows system directory (more installation instructions can be found in the + file README.woe32 in the iconv distribution).<BR> <BR> -Note: Instead of copying libexpat.dll and iconv.dll to Windows - directory, you can add directories +Note: instead of copying libexpat.dll and iconv.dll to the Windows + directory, you can add the directories <CODE>C:\Program Files\Expat-1.95.7\Libs</CODE> and - <CODE>C:\Program Files\iconv-1.9.1\bin</CODE> to <CODE>PATH</CODE> environment + <CODE>C:\Program Files\iconv-1.9.1\bin</CODE> to the <CODE>PATH</CODE> environment variable. -<LI>Being in <CODE>ejabberd\src</CODE> directory run: -<PRE> +<LI CLASS="li-itemize">While in the directory <CODE>ejabberd\src</CODE> run: +<PRE CLASS="verbatim"> configure.bat nmake -f Makefile.win32 -</PRE><LI>Edit file <CODE>ejabberd\src\ejabberd.cfg</CODE> and run -<PRE> +</PRE><LI CLASS="li-itemize">Edit the file <CODE>ejabberd\src\ejabberd.cfg</CODE> and run +<PRE CLASS="verbatim"> werl -s ejabberd -name ejabberd </PRE></UL> <!--TOC subsection Starting--> -<H3><A NAME="htoc10">2.4</A> Starting</H3><!--SEC END --> +<H3 CLASS="subsection"><A NAME="htoc12">2.4</A> Starting</H3><!--SEC END --> <A NAME="sec:starting"></A> -To start <TT>ejabberd</TT>, use the following command: -<PRE> + +Execute the following command to start <TT>ejabberd</TT>: +<PRE CLASS="verbatim"> erl -pa /var/lib/ejabberd/ebin -name ejabberd -s ejabberd </PRE>or -<PRE> +<PRE CLASS="verbatim"> erl -pa /var/lib/ejabberd/ebin -sname ejabberd -s ejabberd -</PRE>In the latter case Erlang node will be identified using only first part of host -name, i. e. other Erlang nodes outside this domain can't contact this node.<BR> +</PRE>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 +this node.<BR> <BR> -Note that when using above command <TT>ejabberd</TT> will search for config file -in current directory and will use current directory for storing user database -and logging.<BR> +Note that when using the above command, <TT>ejabberd</TT> will search for the +configuration file in the current directory and will use the current directory +for storing its user database and for logging.<BR> <BR> -To specify path to config file, log files and Mnesia database directory, -you may use the following command: -<PRE> +To specify the path to the configuration file, the log files and the Mnesia +database directory, you may use the following command: +<PRE CLASS="verbatim"> erl -pa /var/lib/ejabberd/ebin \ -sname ejabberd \ -s ejabberd \ @@ -281,273 +389,356 @@ you may use the following command: -sasl sasl_error_logger \{file,\"/var/log/ejabberd/sasl.log\"\} \ -mnesia dir \"/var/lib/ejabberd/spool\" </PRE> -You can find other useful options in Erlang manual page (<TT>erl -man erl</TT>).<BR> +You can find other useful options in the Erlang manual page +(<TT>erl -man erl</TT>).<BR> <BR> -To use more than 1024 connections, you should set environment variable +To use more than 1024 connections, you should set the environment variable <CODE>ERL_MAX_PORTS</CODE>: -<PRE> +<PRE CLASS="verbatim"> export ERL_MAX_PORTS=32000 -</PRE>Note that with this value <TT>ejabberd</TT> will use more memory (approximately 6MB +</PRE>Note that with this value, <TT>ejabberd</TT> will use more memory (approximately 6 MB more).<BR> <BR> -To reduce memory usage, you may set environment variable +To reduce memory usage, you may set the environment variable <CODE>ERL_FULLSWEEP_AFTER</CODE>: -<PRE> +<PRE CLASS="verbatim"> export ERL_FULLSWEEP_AFTER=0 </PRE>But in this case <TT>ejabberd</TT> can start to work slower.<BR> <BR> <!--TOC section Configuration--> -<H2><A NAME="htoc11">3</A> Configuration</H2><!--SEC END --> +<H2 CLASS="section"><A NAME="htoc13">3</A> Configuration</H2><!--SEC END --> <A NAME="sec:configuration"></A> <!--TOC subsection Initial Configuration--> -<H3><A NAME="htoc12">3.1</A> Initial Configuration</H3><!--SEC END --> +<H3 CLASS="subsection"><A NAME="htoc14">3.1</A> Initial Configuration</H3><!--SEC END --> <A NAME="sec:initconfig"></A> -The configuration file is initially loaded the first time <TT>ejabberd</TT> is -executed, when it is parsed and stored in a database. Subsequently the -configuration is loaded from the database and any commands in the configuration -file are appended to the entries in the database. The configuration file -consists of a sequence of Erlang terms. Parts of lines after <TT>`%'</TT> sign -are ignored. Each term is tuple, where first element is name of option, and -other are option values. E. g. if this file does not contain a ``host'' -definition, then old value stored in the database will be used.<BR> -<BR> -To override old values stored in the database the following lines can be added -in config: -<PRE> + +The configuration file will be loaded the first time you start <TT>ejabberd</TT>. The +content from this file will be parsed and stored in a database. Subsequently the +configuration will be loaded from the database and any commands in the +configuration file are appended to the entries in the database. The +configuration file contains a sequence of Erlang terms. Lines beginning with a +<TT>`%'</TT> 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 +host name(s) stored in the database will be used.<BR> +<BR> +You can override the old values stored in the database by adding next lines to +the configuration file: +<PRE CLASS="verbatim"> override_global. override_local. override_acls. -</PRE>With this lines old global or local options or ACLs will be removed before -adding new ones.<BR> +</PRE>With these lines the old global options, local options and ACLs will be removed +before new ones are added.<BR> <BR> <!--TOC subsubsection Host Names--> -<H4><A NAME="htoc13">3.1.1</A> Host Names</H4><!--SEC END --> +<H4 CLASS="subsubsection"><A NAME="htoc15">3.1.1</A> Host Names</H4><!--SEC END --> <A NAME="sec:confighostname"></A> -Option <TT>hosts</TT> defines a list of Jabber domains that <TT>ejabberd</TT> -serves. E. g. to serve <TT>example.org</TT> and <TT>example.com</TT> domains add -the following line in the config: -<PRE> - {hosts, ["example.org", "example.com"]}. -</PRE> -Option <TT>host</TT> defines one Jabber domain that <TT>ejabberd</TT> serves. -E. g. to serve only <TT>example.org</TT> domain add the following line in the -config: -<PRE> - {host, "example.org"}. -</PRE>It have the same effect as -<PRE> + +The option <TT>hosts</TT> defines a list containing one or more domains that +<TT>ejabberd</TT> will serve.<BR> +<BR> +Examples: +<UL CLASS="itemize"><LI CLASS="li-itemize"> +Serving one domain: +<UL CLASS="itemize"><LI CLASS="li-itemize"> +<PRE CLASS="verbatim"> {hosts, ["example.org"]}. -</PRE> +</PRE><LI CLASS="li-itemize">Backwards compatibility with older <TT>ejabberd</TT> versions can be retained + with: + <PRE CLASS="verbatim"> + {host, "example.org"}. +</PRE></UL> +<LI CLASS="li-itemize">Serving two domains: +<PRE CLASS="verbatim"> + {hosts, ["one.org", "two.org"]}. +</PRE></UL> <!--TOC subsubsection Default Language--> -<H4><A NAME="htoc14">3.1.2</A> Default Language</H4><!--SEC END --> +<H4 CLASS="subsubsection"><A NAME="htoc16">3.1.2</A> Default Language</H4><!--SEC END --> <A NAME="sec:configlanguage"></A> -Option <TT>language</TT> defines default language of <TT>ejabberd</TT> messages, sent -to users. Default value is <TT>"en"</TT>. In order to take effect there must be a -translation file <TT><language>.msg</TT> in <TT>ejabberd</TT> <TT>msgs</TT> directory. -E. g. to use Russian as default language add the following line in the config: -<PRE> + +The option <TT>language</TT> defines the default language of server strings that +can be seen by Jabber clients. If a Jabber client do not support +<TT>xml:lang</TT>, the specified language is used. The default value for the +option <TT>language</TT> is <TT>"en"</TT>. In order to take effect there must be a +translation file <TT><language>.msg</TT> in <TT>ejabberd</TT>'s <TT>msgs</TT> directory.<BR> +<BR> +Examples: +<UL CLASS="itemize"><LI CLASS="li-itemize"> +To set Russian as default language: +<PRE CLASS="verbatim"> {language, "ru"}. -</PRE> +</PRE><LI CLASS="li-itemize">To set Spanish as default language: +<PRE CLASS="verbatim"> + {language, "es"}. +</PRE></UL> <!--TOC subsubsection Access Rules--> -<H4><A NAME="htoc15">3.1.3</A> Access Rules</H4><!--SEC END --> +<H4 CLASS="subsubsection"><A NAME="htoc17">3.1.3</A> Access Rules</H4><!--SEC END --> <A NAME="sec:configaccess"></A> -Access control in <TT>ejabberd</TT> is performed via Access Control Lists (ACL). The -declarations of ACL in config file have following syntax: -<PRE> + +Access control in <TT>ejabberd</TT> is performed via Access Control Lists (ACLs). The +declarations of ACLs in the configuration file have the following syntax: +<PRE CLASS="verbatim"> {acl, <aclname>, {<acltype>, ...}}. </PRE> -<TT><acltype></TT> can be one of following: -<DL COMPACT=compact><DT> -<B><TT>all</TT></B><DD> Matches all JIDs. Example: -<PRE> +<TT><acltype></TT> can be one of the following: +<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description"> +<B><TT>all</TT></B><DD CLASS="dd-description"> Matches all JIDs. Example: +<PRE CLASS="verbatim"> {acl, all, all}. -</PRE><DT><B><TT>{user, <username>}</TT></B><DD> Matches user with name +</PRE><DT CLASS="dt-description"><B><TT>{user, <username>}</TT></B><DD CLASS="dd-description"> Matches the user with the name <TT><username></TT> at the first virtual host. Example: -<PRE> -{acl, admin, {user, "aleksey"}}. -</PRE><DT><B><TT>{user, <username>, <server>}</TT></B><DD> Matches user with JID +<PRE CLASS="verbatim"> +{acl, admin, {user, "yozhik"}}. +</PRE><DT CLASS="dt-description"><B><TT>{user, <username>, <server>}</TT></B><DD CLASS="dd-description"> Matches the user with the JID <TT><username>@<server></TT> and any resource. Example: -<PRE> -{acl, admin, {user, "aleksey", "jabber.ru"}}. -</PRE><DT><B><TT>{server, <server>}</TT></B><DD> Matches any JID from server +<PRE CLASS="verbatim"> +{acl, admin, {user, "yozhik", "example.org"}}. +</PRE><DT CLASS="dt-description"><B><TT>{server, <server>}</TT></B><DD CLASS="dd-description"> Matches any JID from server <TT><server></TT>. Example: -<PRE> -{acl, jabberorg, {server, "jabber.org"}}. -</PRE><DT><B><TT>{user_regexp, <regexp>}</TT></B><DD> Matches local user with name that +<PRE CLASS="verbatim"> +{acl, exampleorg, {server, "example.org"}}. +</PRE><DT CLASS="dt-description"><B><TT>{user_regexp, <regexp>}</TT></B><DD CLASS="dd-description"> Matches any local user with a name that matches <TT><regexp></TT> at the first virtual host. Example: -<PRE> +<PRE CLASS="verbatim"> {acl, tests, {user, "^test[0-9]*$"}}. -</PRE><DT><B><TT>{user_regexp, <regexp>, <server>}</TT></B><DD> Matches user with name - that matches <TT><regexp></TT> and from server <TT><server></TT>. Example: -<PRE> +</PRE><DT CLASS="dt-description"><B><TT>{user_regexp, <regexp>, <server>}</TT></B><DD CLASS="dd-description"> Matches any user with a name + that matches <TT><regexp></TT> at server <TT><server></TT>. Example: +<PRE CLASS="verbatim"> {acl, tests, {user, "^test", "example.org"}}. -</PRE><DT><B><TT>{server_regexp, <regexp>}</TT></B><DD> Matches any JID from server that +</PRE><DT CLASS="dt-description"><B><TT>{server_regexp, <regexp>}</TT></B><DD CLASS="dd-description"> Matches any JID from the server that matches <TT><regexp></TT>. Example: -<PRE> +<PRE CLASS="verbatim"> {acl, icq, {server, "^icq\\."}}. -</PRE><DT><B><TT>{node_regexp, <user_regexp>, <server_regexp>}</TT></B><DD> Matches user - with name that matches <TT><user_regexp></TT> and from server that matches +</PRE><DT CLASS="dt-description"><B><TT>{node_regexp, <user_regexp>, <server_regexp>}</TT></B><DD CLASS="dd-description"> Matches any user + with a name that matches <TT><user_regexp></TT> at any server that matches <TT><server_regexp></TT>. Example: -<PRE> -{acl, aleksey, {node_regexp, "^aleksey$", "^jabber.(ru|org)$"}}. -</PRE><DT><B><TT>{user_glob, <glob>}</TT></B><DD> -<DT><B><TT>{user_glob, <glob>, <server>}</TT></B><DD> -<DT><B><TT>{server_glob, <glob>}</TT></B><DD> -<DT><B><TT>{node_glob, <user_glob>, <server_glob>}</TT></B><DD> This is same as - above, but uses shell glob patterns instead of regexp. These patterns can - have following special characters: - <DL COMPACT=compact><DT> - <B><TT>*</TT></B><DD> matches any string including the null string. - <DT><B><TT>?</TT></B><DD> matches any single character. - <DT><B><TT>[...]</TT></B><DD> matches any of the enclosed characters. Character +<PRE CLASS="verbatim"> +{acl, yohzik, {node_regexp, "^yohzik$", "^example.(com|org)$"}}. +</PRE><DT CLASS="dt-description"><B><TT>{user_glob, <glob>}</TT></B><DD CLASS="dd-description"> +<DT CLASS="dt-description"><B><TT>{user_glob, <glob>, <server>}</TT></B><DD CLASS="dd-description"> +<DT CLASS="dt-description"><B><TT>{server_glob, <glob>}</TT></B><DD CLASS="dd-description"> +<DT CLASS="dt-description"><B><TT>{node_glob, <user_glob>, <server_glob>}</TT></B><DD CLASS="dd-description"> This is the same as + above. However, it uses shell glob patterns instead of regexp. These patterns + can have the following special characters: + <DL CLASS="description" COMPACT=compact><DT CLASS="dt-description"> + <B><TT>*</TT></B><DD CLASS="dd-description"> matches any string including the null string. + <DT CLASS="dt-description"><B><TT>?</TT></B><DD CLASS="dd-description"> matches any single character. + <DT CLASS="dt-description"><B><TT>[...]</TT></B><DD CLASS="dd-description"> matches any of the enclosed characters. Character ranges are specified by a pair of characters separated by a <TT>`-'</TT>. - If the first character after <TT>`['</TT> is a <TT>`!'</TT>, then any + If the first character after <TT>`['</TT> is a <TT>`!'</TT>, any character not enclosed is matched. </DL> </DL> The following ACLs are pre-defined: -<DL COMPACT=compact><DT> -<B><TT>all</TT></B><DD> Matches all JIDs. -<DT><B><TT>none</TT></B><DD> Matches none JIDs. +<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description"> +<B><TT>all</TT></B><DD CLASS="dd-description"> Matches any JID. +<DT CLASS="dt-description"><B><TT>none</TT></B><DD CLASS="dd-description"> Matches no JID. </DL> -An entry allowing or denying access to different services would look similar to +An entry allowing or denying access to different services looks similar to this: -<PRE> +<PRE CLASS="verbatim"> {access, <accessname>, [{allow, <aclname>}, {deny, <aclname>}, ... ]}. </PRE>When a JID is checked to have access to <TT><accessname></TT>, the server -sequentially checks if this JID mathes one of the ACLs that are second elements -in each tuple in list. If it is matched, then the first element of matched -tuple is returned else ``<TT>deny</TT>'' is returned.<BR> +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 “<TT>deny</TT>” is returned.<BR> <BR> Example: -<PRE> +<PRE CLASS="verbatim"> {access, configure, [{allow, admin}]}. {access, something, [{deny, badmans}, {allow, all}]}. </PRE> -Following access rules pre-defined: -<DL COMPACT=compact><DT> -<B><TT>all</TT></B><DD> Always returns ``<TT>allow</TT>'' -<DT><B><TT>none</TT></B><DD> Always returns ``<TT>deny</TT>'' +The following access rules are pre-defined: +<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description"> +<B><TT>all</TT></B><DD CLASS="dd-description"> Always returns “<TT>allow</TT>” +<DT CLASS="dt-description"><B><TT>none</TT></B><DD CLASS="dd-description"> Always returns “<TT>deny</TT>” </DL> -<!--TOC subsubsection Shapers Configuration--> +<!--TOC subsubsection Shapers--> -<H4><A NAME="htoc16">3.1.4</A> Shapers Configuration</H4><!--SEC END --> +<H4 CLASS="subsubsection"><A NAME="htoc18">3.1.4</A> Shapers</H4><!--SEC END --> <A NAME="sec:configshaper"></A> -With shapers is possible to bound connection traffic. The declarations of -shapers in config file have following syntax: -<PRE> + +Shapers enable you to limit connection traffic. The syntax of +shapers is like this: +<PRE CLASS="verbatim"> {shaper, <shapername>, <kind>}. -</PRE>Currently implemented only one kind of shaper: <TT>maxrate</TT>. It have +</PRE>Currently only one kind of shaper called <TT>maxrate</TT> is available. It has the following syntax: -<PRE> +<PRE CLASS="verbatim"> {maxrate, <rate>} -</PRE>where <TT><rate></TT> means maximum allowed incomig rate in bytes/second. -E. g. to define shaper with name ``<TT>normal</TT>'' and maximum allowed rate -1000 bytes/s, add following line in config: -<PRE> +</PRE>where <TT><rate></TT> stands for the maximum allowed incomig rate in bytes per +second.<BR> +<BR> +Examples: +<UL CLASS="itemize"><LI CLASS="li-itemize"> +To define a shaper named “<TT>normal</TT>” with traffic speed limited to +1,000 bytes/second: +<PRE CLASS="verbatim"> {shaper, normal, {maxrate, 1000}}. -</PRE> +</PRE><LI CLASS="li-itemize">To define a shaper named “<TT>fast</TT>” with traffic speed limited to +50,000 bytes/second: +<PRE CLASS="verbatim"> + {shaper, fast, {maxrate, 50000}}. +</PRE></UL> <!--TOC subsubsection Listened Sockets--> -<H4><A NAME="htoc17">3.1.5</A> Listened Sockets</H4><!--SEC END --> +<H4 CLASS="subsubsection"><A NAME="htoc19">3.1.5</A> Listened Sockets</H4><!--SEC END --> <A NAME="sec:configlistened"></A> -Option <TT>listen</TT> defines list of listened sockets and what services -runned on them. Each element of list is a tuple with following elements: -<UL><LI> -Port number; -<LI>Module that serves this port; -<LI>Options to this module. + +The option <TT>listen</TT> defines for which addresses and ports <TT>ejabberd</TT> +will listen and what services will be run on them. Each element of the list is a +tuple with the following elements: +<UL CLASS="itemize"><LI CLASS="li-itemize"> +Port number. +<LI CLASS="li-itemize">Module that serves this port. +<LI CLASS="li-itemize">Options to this module. </UL> -Currently these modules are implemented: -<DL COMPACT=compact><DT> - <B><TT>ejabberd_c2s</TT></B><DD> This module serves C2S connections.<BR> -<BR> -The following options are defined: - <DL COMPACT=compact><DT> - <B><TT>{access, <access rule>}</TT></B><DD> This option defines access of users - to this C2S port. Default value is ``<TT>all</TT>''. - <DT><B><TT>{shaper, <access rule>}</TT></B><DD> This option is like previous, but - use shapers instead of ``<TT>allow</TT>'' and ``<TT>deny</TT>''. Default - value is ``<TT>none</TT>''. - <DT><B><TT>{ip, IPAddress}</TT></B><DD> This option specifies which network interface to - listen on. For example <CODE>{ip, {192, 168, 1, 1}}</CODE>. - <DT><B><TT>inet6</TT></B><DD> Set up the socket for IPv6. - <DT><B><TT>starttls</TT></B><DD> This option specifies that STARTTLS extension is available - on connections to this port. You should also set ``<CODE>certfile</CODE>'' - option. - <DT><B><TT>tls</TT></B><DD> This option specifies that traffic on this port will be - encrypted using SSL immediately after connecting. You should also set - ``<CODE>certfile</CODE>'' option. - <DT><B><TT>ssl</TT></B><DD> This option specifies that traffic on this port will be - encrypted using SSL. You should also set ``<CODE>certfile</CODE>'' option. It - is recommended to use <TT>tls</TT> option instead. - <DT><B><TT>{certfile, Path}</TT></B><DD> Path to a file containing the SSL certificate. - </DL> - <DT><B><TT>ejabberd_s2s_in</TT></B><DD> This module serves incoming S2S connections. - <DT><B><TT>ejabberd_service</TT></B><DD> This module serves connections from Jabber - services (i. e. that use the <TT>jabber:component:accept</TT> namespace).<BR> -<BR> -The following additional options are defined for <TT>ejabberd_service</TT> - (options <TT>access</TT>, <TT>shaper</TT>, <TT>ip</TT>, <TT>inet6</TT> are - still valid): - <DL COMPACT=compact><DT> - <B><TT>{host, Hostname, [HostOptions]}</TT></B><DD> This option defines hostname of connected - service and allows to specify additional options, e. g. - <TT>{password, Secret}</TT>. - <DT><B><TT>{hosts, [Hostnames], [HostOptions]}</TT></B><DD> The same as above, but allows to - specify several hostnames. - </DL> - <DT><B><TT>ejabberd_http</TT></B><DD> This module serves incoming HTTP connections.<BR> + +Currently next modules are implemented: +<BLOCKQUOTE CLASS="table"><DIV CLASS="center"><DIV CLASS="center"><HR WIDTH="80%" SIZE=2></DIV> + <TABLE BORDER=1 CELLSPACING=0 CELLPADDING=1> +<TR><TD ALIGN=left NOWRAP><TT>ejabberd_c2s</TT></TD> +<TD ALIGN=left NOWRAP>Description</TD> +<TD ALIGN=left NOWRAP>Handles c2s connections.</TD> +</TR> +<TR><TD ALIGN=left NOWRAP> </TD> +<TD ALIGN=left NOWRAP>Options</TD> +<TD ALIGN=left NOWRAP><TT>access</TT>, <TT>certfile</TT>, <TT>inet6</TT>, + <TT>ip</TT>, <TT>shaper</TT>, <TT>ssl</TT>, <TT>tls</TT>, + <TT>starttls</TT>,</TD> +</TR> +<TR><TD ALIGN=left NOWRAP> </TD> +<TD ALIGN=left NOWRAP> </TD> +<TD ALIGN=left NOWRAP><TT>starttls_required</TT></TD> +</TR> +<TR><TD ALIGN=left NOWRAP><TT>ejabberd_s2s_in</TT></TD> +<TD ALIGN=left NOWRAP>Description</TD> +<TD ALIGN=left NOWRAP>Handles incoming s2s + connections.</TD> +</TR> +<TR><TD ALIGN=left NOWRAP> </TD> +<TD ALIGN=left NOWRAP>Options</TD> +<TD ALIGN=left NOWRAP><TT>inet6</TT>, <TT>ip</TT></TD> +</TR> +<TR><TD ALIGN=left NOWRAP><TT>ejabberd_service</TT></TD> +<TD ALIGN=left NOWRAP>Description</TD> +<TD ALIGN=left NOWRAP>Interacts with external + components (*).</TD> +</TR> +<TR><TD ALIGN=left NOWRAP> </TD> +<TD ALIGN=left NOWRAP>Options</TD> +<TD ALIGN=left NOWRAP><TT>access</TT>, <TT>hosts</TT>, <TT>inet6</TT>, + <TT>ip</TT>, <TT>shaper</TT></TD> +</TR> +<TR><TD ALIGN=left NOWRAP><TT>ejabberd_http</TT></TD> +<TD ALIGN=left NOWRAP>Description</TD> +<TD ALIGN=left NOWRAP>Handles incoming HTTP + connections.</TD> +</TR> +<TR><TD ALIGN=left NOWRAP> </TD> +<TD ALIGN=left NOWRAP>Options</TD> +<TD ALIGN=left NOWRAP><TT>certfile</TT>, <TT>http_poll</TT>, + <TT>inet6</TT>, <TT>ip</TT>, <TT>tls</TT>, <TT>web_admin</TT></TD> +</TR></TABLE> +<DIV CLASS="center"><HR WIDTH="80%" SIZE=2></DIV></DIV></BLOCKQUOTE> +(*) The mechanism for <A HREF="http://ejabberd.jabber.ru/tutorials-transports">external components</A> is defined in Jabber Component Protocol (<A HREF="http://www.jabber.org/jeps/jep-0114.html">JEP-0114</A>).<BR> <BR> -The following options are defined: - <DL COMPACT=compact><DT> - <B><TT>http_poll</TT></B><DD> This option enables <A HREF="http://www.jabber.org/jeps/jep-0025.html">JEP-0025</A> (HTTP Polling) - support. It is available then at <CODE>http://server:port/http-poll/</CODE>.<BR> +The following options are available: +<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description"> + <B><TT>{access, <access rule>}</TT></B><DD CLASS="dd-description"> This option defines + access to the port. The default value is “<TT>all</TT>”. + <DT CLASS="dt-description"><B><TT>{certfile, Path}</TT></B><DD CLASS="dd-description"> Path to a file containing the SSL certificate. + <DT CLASS="dt-description"><B><TT>{hosts, [Hostnames], [HostOptions]}</TT></B><DD CLASS="dd-description"> This option + defines one or more hostnames of connected services and enables you to + specify additional options including <TT>{password, Secret}</TT>. + <DT CLASS="dt-description"><B><TT>http_poll</TT></B><DD CLASS="dd-description"> + This option enables HTTP Polling (<A HREF="http://www.jabber.org/jeps/jep-0025.html">JEP-0025</A>) support. HTTP Polling + enables access via HTTP requests to <TT>ejabberd</TT> from behind firewalls which + do not allow outgoing sockets on port 5222.<BR> <BR> -<DT><B><TT>web_admin</TT></B><DD> This option enables web-based interface for <TT>ejabberd</TT> - administration which is available at <CODE>http://server:port/admin/</CODE>, - login and password should be equal to username and password of one of - registered users who have permission defined in ``configure'' access rule. - </DL> +If HTTP Polling is enabled, it will be available at + <CODE>http://server:port/http-poll/</CODE>. 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 + <A HREF="http://jwchat.sourceforge.net/">JWChat</A> (there is a tutorial to + <A HREF="http://ejabberd.jabber.ru/jwchat">install JWChat</A> with + instructions for <TT>ejabberd</TT>). + <DT CLASS="dt-description"><B><TT>inet6</TT></B><DD CLASS="dd-description"> Set up the socket for IPv6. + <DT CLASS="dt-description"><B><TT>{ip, IPAddress}</TT></B><DD CLASS="dd-description"> This option specifies which network + interface to listen for. For example <CODE>{ip, {192, 168, 1, 1}}</CODE>. + <DT CLASS="dt-description"><B><TT>{shaper, <access rule>}</TT></B><DD CLASS="dd-description"> This option defines a + shaper for the port (see section <A HREF="#sec:configshaper">3.1.4</A>). The default value + is “<TT>none</TT>”. + <DT CLASS="dt-description"><B><TT>ssl</TT></B><DD CLASS="dd-description"> This option specifies that traffic on + the port will be encrypted using SSL. You should also set the + <TT>certfile</TT> option. It is recommended to use the <TT>tls</TT> option + instead. + <DT CLASS="dt-description"><B><TT>starttls</TT></B><DD CLASS="dd-description"> This option + specifies that STARTTLS encryption is available on connections to the port. + You should also set the <TT>certfile</TT> option. + <DT CLASS="dt-description"><B><TT>starttls_required</TT></B><DD CLASS="dd-description"> This option + specifies that STARTTLS encryption is required on connections to the port. + No unencrypted connections will be allowed. You should also set the + <TT>certfile</TT> option. + <DT CLASS="dt-description"><B><TT>tls</TT></B><DD CLASS="dd-description"> This option specifies that traffic on + the port will be encrypted using SSL immediately after connecting. You + should also set the <TT>certfile</TT> option. + <DT CLASS="dt-description"><B><TT>web_admin</TT></B><DD CLASS="dd-description"> This option + enables the web interface for <TT>ejabberd</TT> administration which is available + at <CODE>http://server:port/admin/</CODE>. Login and password are the username and + password of one of the registered users who are granted access by the + “configure” access rule. </DL> -For example, the following configuration defines that: -<UL><LI> -C2S connections are listened on port 5222 and 5223 (SSL) and denied for - user ``<TT>bad</TT>'' -<LI>S2S connections are listened on port 5269 -<LI>HTTP connections are listened on port 5280 and administration interface - and HTTP Polling support are enabled -<LI>All users except admins have traffic limit 1000 B/s -<LI>AIM transport <TT>aim.example.org</TT> is connected to port 5233 with - password ``<TT>aimsecret</TT>'' -<LI>JIT transports <TT>icq.example.org</TT> and <TT>sms.example.org</TT> are - connected to port 5234 with password ``<TT>jitsecret</TT>'' -<LI>MSN transport <TT>msn.example.org</TT> is connected to port 5235 with - password ``<TT>msnsecret</TT>'' -<LI>Yahoo! transport <TT>yahoo.example.org</TT> is connected to port 5236 with - password ``<TT>yahoosecret</TT>'' -<LI>Gadu-Gadu transport <TT>gg.example.org</TT> is connected to port 5237 with - password ``<TT>ggsecret</TT>'' -<LI>ILE service <TT>ile.example.org</TT> is connected to port 5238 with - password ``<TT>ilesecret</TT>'' +For instance, the following configuration defines that: +<UL CLASS="itemize"><LI CLASS="li-itemize"> +c2s connections are listened for on port 5222 and 5223 (SSL) and denied + for the user “<TT>bad</TT>” +<LI CLASS="li-itemize">s2s connections are listened for on port 5269 +<LI CLASS="li-itemize">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 <A HREF="#sec:webadm">3.3.1</A> shows how exactly this can be done. +<LI CLASS="li-itemize">All users except for the administrators have a traffic of limit + 1,000 Bytes/second +<LI CLASS="li-itemize">The + <A HREF="http://ejabberd.jabber.ru/pyaimt">AIM transport</A> + <TT>aim.example.org</TT> is connected to port 5233 with password + “<TT>aimsecret</TT>” +<LI CLASS="li-itemize">The ICQ transport JIT (<TT>icq.example.org</TT> and + <TT>sms.example.org</TT>) is connected to port 5234 with password + “<TT>jitsecret</TT>” +<LI CLASS="li-itemize">The + <A HREF="http://ejabberd.jabber.ru/pymsnt">MSN transport</A> + <TT>msn.example.org</TT> is connected to port 5235 with password + “<TT>msnsecret</TT>” +<LI CLASS="li-itemize">The + <A HREF="http://ejabberd.jabber.ru/yahoo-transport-2">Yahoo! transport</A> + <TT>yahoo.example.org</TT> is connected to port 5236 with password + “<TT>yahoosecret</TT>” +<LI CLASS="li-itemize">The <A HREF="http://ejabberd.jabber.ru/jabber-gg-transport">Gadu-Gadu transport</A> <TT>gg.example.org</TT> is + connected to port 5237 with password “<TT>ggsecret</TT>” +<LI CLASS="li-itemize">The + <A HREF="http://ejabberd.jabber.ru/jmc">Jabber Mail Component</A> + <TT>jmc.example.org</TT> is connected to port 5238 with password + “<TT>jmcsecret</TT>” </UL> -<PRE> +<PRE CLASS="verbatim"> {acl, blocked, {user, "bad"}}. {access, c2s, [{deny, blocked}, {allow, all}]}. @@ -570,13 +761,13 @@ C2S connections are listened on port 5222 and 5223 (SSL) and denied for [{password, "yahoosecret"}]}]}, {5237, ejabberd_service, [{host, "gg.example.org", [{password, "ggsecret"}]}]}, - {5238, ejabberd_service, [{host, "ile.example.org", - [{password, "ilesecret"}]}]} + {5238, ejabberd_service, [{host, "jmc.example.org", + [{password, "jmcsecret"}]}]} ] }. -</PRE>Note, that for jabberd14- or wpjabberd-based services you have to make the -transports log and do XDB by themselves: -<PRE> +</PRE>Note, that for jabberd 1.4- or WPJabber-based +services you have to make the transports log and do XDB by themselves: +<PRE CLASS="verbatim"> <!-- You have to add elogger and rlogger entries here when using ejabberd. In this case the transport will do the logging. @@ -591,8 +782,8 @@ transports log and do XDB by themselves: <!-- Some Jabber server implementations do not provide - XDB services (for example jabberd 2.0 and ejabberd). - xdb_file_so is loaded in to handle all XDB requests. + XDB services (for example, jabberd2 and ejabberd). + xdb_file.so is loaded in to handle all XDB requests. --> <xdb id="xdb"> @@ -608,16 +799,18 @@ transports log and do XDB by themselves: </PRE> <!--TOC subsubsection Modules--> -<H4><A NAME="htoc18">3.1.6</A> Modules</H4><!--SEC END --> +<H4 CLASS="subsubsection"><A NAME="htoc20">3.1.6</A> Modules</H4><!--SEC END --> <A NAME="sec:configmodules"></A> -Option <TT>modules</TT> defines the list of modules that will be loaded after -<TT>ejabberd</TT> startup. Each list element is a tuple where first element is a -name of a module and second is list of options to this module. See -section <A HREF="#sec:modules">A</A> for detailed information on each module.<BR> + +The option <TT>modules</TT> defines the list of modules that will be loaded after +<TT>ejabberd</TT> 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 HREF="#sec:modules">A</A> for detailed information about each +module.<BR> <BR> Example: -<PRE> +<PRE CLASS="verbatim"> {modules, [{mod_register, []}, {mod_roster, []}, @@ -628,7 +821,7 @@ Example: {mod_vcard, []}, {mod_offline, []}, {mod_announce, [{access, announce}]}, - {mod_echo, [{host, "echo.example.org"}]}, + {mod_echo, [{hosts, ["echo.example.org"]}]}, {mod_private, []}, {mod_irc, []}, {mod_muc, []}, @@ -638,268 +831,426 @@ Example: {mod_version, []} ]}. </PRE> -<!--TOC subsubsection Virtual Host Configuration--> +<!--TOC subsubsection Virtual Hosting--> -<H4><A NAME="htoc19">3.1.7</A> Virtual Host Configuration</H4><!--SEC END --> +<H4 CLASS="subsubsection"><A NAME="htoc21">3.1.7</A> Virtual Hosting</H4><!--SEC END --> <A NAME="sec:configvirtualhost"></A> -Options can be defined separately for different virtual hosts using -<TT>host_config</TT> option. It have the have following syntax: -<PRE> + +Options can be defined separately for every virtual host using the +<TT>host_config</TT> option. It has the following +syntax: +<PRE CLASS="verbatim"> {host_config, <hostname>, [<option>, <option>, ...]}. </PRE> -Example: -<PRE> -{host_config, "example.org", [{auth_method, internal}]}. - -{host_config, "example.com", [{auth_method, ldap}, +Examples: +<UL CLASS="itemize"><LI CLASS="li-itemize"> +Domain <TT>one.org</TT> is using the internal authentication method while + domain <TT>two.org</TT> is using the LDAP server running on the domain + <TT>localhost</TT> to perform authentication: +<PRE CLASS="verbatim"> +{host_config, "one.org", [{auth_method, internal}]}. + +{host_config, "two.org", [{auth_method, ldap}, {ldap_servers, ["localhost"]}, {ldap_uidattr, "uid"}, {ldap_rootdn, "dc=localdomain"}, {ldap_rootdn, "dc=example,dc=com"}, {ldap_password, ""}]}. -</PRE> +</PRE><LI CLASS="li-itemize">Domain <TT>one.org</TT> is using ODBC to perform authentication + while domain <TT>two.org</TT> is using the LDAP servers running on the domains + <TT>localhost</TT> and <TT>otherhost</TT>: +<PRE CLASS="verbatim"> +{host_config, "one.org", [{auth_method, odbc}, + {odbc_server, "DSN=ejabberd;UID=ejabberd;PWD=ejabberd"}]}. + +{host_config, "two.org", [{auth_method, ldap}, + {ldap_servers, ["localhost", "otherhost"]}, + {ldap_uidattr, "uid"}, + {ldap_rootdn, "dc=localdomain"}, + {ldap_rootdn, "dc=example,dc=com"}, + {ldap_password, ""}]}. +</PRE></UL> +<!--TOC subsection Creating an Initial Administrator--> + +<H3 CLASS="subsection"><A NAME="htoc22">3.2</A> Creating an Initial Administrator</H3><!--SEC END --> + +<A NAME="sec:initialadmin"></A> +Before the web interface can be entered to perform administration tasks, an +account with administrator rights is needed on your <TT>ejabberd</TT> deployment.<BR> +<BR> +Instructions to create an initial administrator account: +<OL CLASS="enumerate" type=1><LI CLASS="li-enumerate"> +Register an account on your <TT>ejabberd</TT> deployment. An account can be + created in two ways: + <OL CLASS="enumerate" type=a><LI CLASS="li-enumerate"> + Using the tool <TT>ejabberdctl</TT> (see + section <A HREF="#sec:ejabberdctl">3.3.2</A>): + <PRE CLASS="verbatim"> +% ejabberdctl node@host register admin example.org password +</PRE><LI CLASS="li-enumerate">Using In-Band Registration (see section <A HREF="#sec:modregister">A.12</A>): you can + use a Jabber client to register an account. + </OL> +<LI CLASS="li-enumerate">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. + <PRE CLASS="verbatim"> + {acl, admins, {user, "admin", "example.org"}}. + {access, configure, [{allow, admins}]}. +</PRE><LI CLASS="li-enumerate">Restart <TT>ejabberd</TT> to load the new configuration. +<LI CLASS="li-enumerate">Open the web interface (<CODE>http://server:port/admin/</CODE>) in your + favourite browser. Make sure to enter the <EM>full</EM> JID as username (in this + example: <TT>admin@example.org</TT>. The reason that you also need to enter the + suffix, is because <TT>ejabberd</TT>'s virtual hosting support. +</OL> <!--TOC subsection Online Configuration and Monitoring--> -<H3><A NAME="htoc20">3.2</A> Online Configuration and Monitoring</H3><!--SEC END --> +<H3 CLASS="subsection"><A NAME="htoc23">3.3</A> Online Configuration and Monitoring</H3><!--SEC END --> <A NAME="sec:onlineconfig"></A> -<!--TOC subsubsection Web-based Administration Interface--> +<!--TOC subsubsection Web Interface--> -<H4><A NAME="htoc21">3.2.1</A> Web-based Administration Interface</H4><!--SEC END --> +<H4 CLASS="subsubsection"><A NAME="htoc24">3.3.1</A> Web Interface</H4><!--SEC END --> <A NAME="sec:webadm"></A> -To perform online reconfiguration of <TT>ejabberd</TT> you need to enable -<TT>ejabberd_http</TT> listener with option <TT>web_admin</TT> (see -section <A HREF="#sec:configlistened">3.1.5</A>). After that you can open URL -<CODE>http://server:port/admin/</CODE> with you favorite web-browser and enter -username and password of an <TT>ejabberd</TT> user with administrator rights. E. g. -with such config: -<PRE> - ... - {host, "example.org"}. - ... - {listen, - [... - {5280, ejabberd_http, [web_admin]}, - ... - ] - }. -</PRE>you should enter URL <CODE>http://example.org:5280/admin/</CODE>. After -authentication you should see something like in figure <A HREF="#fig:webadmmain">1</A>. -<BLOCKQUOTE><DIV ALIGN=center><DIV ALIGN=center><HR WIDTH="80%" SIZE=2></DIV> + +To perform online configuration of <TT>ejabberd</TT> you need to enable the +<TT>ejabberd_http</TT> listener with the option <TT>web_admin</TT> (see +section <A HREF="#sec:configlistened">3.1.5</A>). Then you can open +<CODE>http://server:port/admin/</CODE> in your favourite web browser. You +will be asked to enter the username (the <EM>full</EM> Jabber ID) and password +of an <TT>ejabberd</TT> user with administrator rights. After authentication +you will see a page similar to figure <A HREF="#fig:webadmmain">1</A>. +<BLOCKQUOTE CLASS="figure"><DIV CLASS="center"><DIV CLASS="center"><HR WIDTH="80%" SIZE=2></DIV> <IMG SRC="webadmmain.png"> <BR> -<DIV ALIGN=center>Figure 1: Web-administration top page</DIV><BR> +<BR> +<DIV CLASS="center">Figure 1: Top page from the web interface</DIV><BR> +<BR> <A NAME="fig:webadmmain"></A> -<DIV ALIGN=center><HR WIDTH="80%" SIZE=2></DIV></DIV></BLOCKQUOTE> -Here you can edit access restrictions, manage users, create backup files, -manage DB, enable/disable listened ports, and view statistics.<BR> +<DIV CLASS="center"><HR WIDTH="80%" SIZE=2></DIV></DIV></BLOCKQUOTE> +Here you can edit access restrictions, manage users, create backups, +manage the database, enable/disable ports listened for, view server +statistics,...<BR> <BR> -<!--TOC subsubsection <TT>ejabberdctl</TT> tool--> +Examples: +<UL CLASS="itemize"><LI CLASS="li-itemize"> +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 <CODE>http://example.org:5280/admin/</CODE> to + administer all virtual hosts or to + <CODE>http://example.org:5280/admin/server/two.org/</CODE> to administer only the + virtual host <TT>two.org</TT>. 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 <TT>ejabberd</TT>. In this example you can enter as username + “<TT>admin@one.org</TT>” to administer all virtual hosts (first URL). If you + log in with “<TT>admin@two.org</TT>” on<BR> +<CODE>http://example.org:5280/admin/server/two.org/</CODE> you can only administer + the virtual host <TT>two.org</TT>. + <PRE CLASS="verbatim"> + ... + {acl, admins, {user, "admin", "one.org"}}. + {host_config, "two.org", [{acl, admins, {user, "admin", "two.org"}}]}. + {access, configure, [{allow, admins}]}. + ... + {hosts, ["example.org"]}. + ... + {listen, + [... + {5280, ejabberd_http, [http_poll, web_admin]}, + ... + ] + }. +</PRE><LI CLASS="li-itemize">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 <CODE>https://192.168.1.1:5280/admin/</CODE>: + <PRE CLASS="verbatim"> + ... + {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"}]}, + ... + ] + }. +</PRE></UL> +<!--TOC subsubsection <TT>ejabberdctl</TT>--> -<H4><A NAME="htoc22">3.2.2</A> <TT>ejabberdctl</TT> tool</H4><!--SEC END --> +<H4 CLASS="subsubsection"><A NAME="htoc25">3.3.2</A> <TT>ejabberdctl</TT></H4><!--SEC END --> <A NAME="sec:ejabberdctl"></A> -It is possible to do some administration operations using <TT>ejabberdctl</TT> -command-line tool. You can check available options running this command -without arguments: -<PRE> +It is possible to do some administration operations using the command +line tool <TT>ejabberdctl</TT>. You can list all available options by +running <TT>ejabberdctl</TT> without arguments: +<PRE CLASS="verbatim"> % ejabberdctl Usage: ejabberdctl node command Available commands: + status get ejabberd status stop stop ejabberd restart restart ejabberd reopen-log reopen log file - register user password register a user - unregister user unregister a user - backup file store a database backup in file + 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 in a text 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 </PRE> +Additional information: +<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description"> +<B><TT>reopen-log </TT></B><DD CLASS="dd-description"> If you use a tool to rotate logs, you have to configure it + so that this command is executed after each rotation. +<DT CLASS="dt-description"><B><TT>backup, restore, install-fallback, dump, load</TT></B><DD CLASS="dd-description"> You can use these + commands to create and restore backups. +<DT CLASS="dt-description"><B><TT>import-file, import-dir</TT></B><DD CLASS="dd-description"> + These options can be used to migrate from other Jabber/XMPP servers. There + exist tutorials to <A HREF="http://ejabberd.jabber.ru/jabberd1-to-ejabberd">migrate from jabberd 1.4</A> + and to <A HREF="http://ejabberd.jabber.ru/jabberd2-to-ejabberd">migrate from jabberd2</A>. +<DT CLASS="dt-description"><B><TT>delete-expired-messages</TT></B><DD CLASS="dd-description"> 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. +</DL> +<!--TOC section Firewall Settings--> + +<H2 CLASS="section"><A NAME="htoc26">4</A> Firewall Settings</H2><!--SEC END --> + +<A NAME="sec:firewall"></A> + +You need to take the following ports in mind when configuring your firewall: +<BLOCKQUOTE CLASS="table"><DIV CLASS="center"><DIV CLASS="center"><HR WIDTH="80%" SIZE=2></DIV> + <TABLE BORDER=1 CELLSPACING=0 CELLPADDING=1> +<TR><TD ALIGN=left NOWRAP>Port</TD> +<TD ALIGN=left NOWRAP>Description</TD> +</TR> +<TR><TD ALIGN=left NOWRAP>5222</TD> +<TD ALIGN=left NOWRAP>SASL and unencrypted c2s connections.</TD> +</TR> +<TR><TD ALIGN=left NOWRAP>5223</TD> +<TD ALIGN=left NOWRAP>Obsolete SSL c2s connections.</TD> +</TR> +<TR><TD ALIGN=left NOWRAP>5269</TD> +<TD ALIGN=left NOWRAP>s2s connections.</TD> +</TR> +<TR><TD ALIGN=left NOWRAP>4369</TD> +<TD ALIGN=left NOWRAP>Only for clustering (see <A HREF="#sec:clustering">6</A>).</TD> +</TR> +<TR><TD ALIGN=left NOWRAP>port range</TD> +<TD ALIGN=left NOWRAP>Only for clustring (see <A HREF="#sec:clustering">6</A>). This range + is configurable (see <A HREF="#sec:starting">2.4</A>).</TD> +</TR></TABLE> +<DIV CLASS="center"><HR WIDTH="80%" SIZE=2></DIV></DIV></BLOCKQUOTE> +<!--TOC section SRV Records--> + +<H2 CLASS="section"><A NAME="htoc27">5</A> SRV Records</H2><!--SEC END --> + +<A NAME="sec:srv"></A> + +<UL CLASS="itemize"><LI CLASS="li-itemize"> +General information: + <A HREF="http://en.wikipedia.org/wiki/SRV_record">SRV record</A> +<LI CLASS="li-itemize">Practical information: + <A HREF="http://jabberd.jabberstudio.org/2/docs/section05.html#5_7">Setting DNS SRV Records</A> +</UL> <!--TOC section Clustering--> -<H2><A NAME="htoc23">4</A> Clustering</H2><!--SEC END --> +<H2 CLASS="section"><A NAME="htoc28">6</A> Clustering</H2><!--SEC END --> <A NAME="sec:clustering"></A> -<!--TOC subsection How it works--> -<H3><A NAME="htoc24">4.1</A> How it works</H3><!--SEC END --> +<!--TOC subsection How it Works--> + +<H3 CLASS="subsection"><A NAME="htoc29">6.1</A> How it Works</H3><!--SEC END --> <A NAME="sec:howitworks"></A> + A Jabber domain is served by one or more <TT>ejabberd</TT> nodes. These nodes can -be runned on different machines that are connected via a network. They all +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 <TT>~ejabberd/.erlang.cookie</TT> must be the same on all nodes). This is -needed because all nodes exchange information about connected users, S2S +needed because all nodes exchange information about connected users, s2s connections, registered services, etc...<BR> <BR> -Each <TT>ejabberd</TT> node have following modules: -<UL><LI> -router; -<LI>local router. -<LI>session manager; -<LI>S2S manager; +Each <TT>ejabberd</TT> node has the following modules: +<UL CLASS="itemize"><LI CLASS="li-itemize"> +router, +<LI CLASS="li-itemize">local router, +<LI CLASS="li-itemize">session manager, +<LI CLASS="li-itemize">s2s manager. </UL> <!--TOC subsubsection Router--> -<H4><A NAME="htoc25">4.1.1</A> Router</H4><!--SEC END --> +<H4 CLASS="subsubsection"><A NAME="htoc30">6.1.1</A> Router</H4><!--SEC END --> + This module is the main router of Jabber packets on each node. It -routes them based on their destinations domains. It uses a global -routing table. A domain of packet destination is searched in the -routing table, and if it is found, then the packet is routed to -appropriate process. If no, then it is sent to the S2S manager.<BR> +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.<BR> <BR> <!--TOC subsubsection Local Router--> -<H4><A NAME="htoc26">4.1.2</A> Local Router</H4><!--SEC END --> +<H4 CLASS="subsubsection"><A NAME="htoc31">6.1.2</A> Local Router</H4><!--SEC END --> + This module routes packets which have a destination domain equal to -this server name. If destination JID has a non-empty user part, then -it is routed to the session manager, else it is processed depending on -its content.<BR> +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.<BR> <BR> <!--TOC subsubsection Session Manager--> -<H4><A NAME="htoc27">4.1.3</A> Session Manager</H4><!--SEC END --> +<H4 CLASS="subsubsection"><A NAME="htoc32">6.1.3</A> Session Manager</H4><!--SEC END --> + -This module routes packets to local users. It searches to what user -resource a packet must be sent via a presence table. Then packet is -either routed to appropriate C2S process, or stored in offline +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.<BR> <BR> -<!--TOC subsubsection S2S Manager--> +<!--TOC subsubsection s2s Manager--> + +<H4 CLASS="subsubsection"><A NAME="htoc33">6.1.4</A> s2s Manager</H4><!--SEC END --> -<H4><A NAME="htoc28">4.1.4</A> S2S Manager</H4><!--SEC END --> This module routes packets to other Jabber servers. First, it -checks if an opened S2S connection from the domain of the packet -source to the domain of packet destination is existing. If it is -existing, then the S2S manager routes the packet to the process -serving this connection, else a new connection is opened.<BR> +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.<BR> <BR> -<!--TOC subsection How to setup ejabberd cluster--> +<!--TOC subsection Clustering Setup--> -<H3><A NAME="htoc29">4.2</A> How to setup ejabberd cluster</H3><!--SEC END --> +<H3 CLASS="subsection"><A NAME="htoc34">6.2</A> Clustering Setup</H3><!--SEC END --> <A NAME="sec:cluster"></A> -Suppose you already setuped ejabberd on one of machines (<TT>first</TT>), and -you need to setup another one to make <TT>ejabberd</TT> cluster. Then do + +Suppose you already configured <TT>ejabberd</TT> on one machine named (<TT>first</TT>), +and you need to setup another one to make an <TT>ejabberd</TT> cluster. Then do following steps: -<OL type=1><LI> +<OL CLASS="enumerate" type=1><LI CLASS="li-enumerate"> Copy <CODE>~ejabberd/.erlang.cookie</CODE> file from <TT>first</TT> to <TT>second</TT>.<BR> <BR> -(alt) You can also add ``<CODE>-cookie content_of_.erlang.cookie</CODE>'' - option to all ``<TT>erl</TT>'' commands below.<BR> +(alt) You can also add “<CODE>-cookie content_of_.erlang.cookie</CODE>” + option to all “<TT>erl</TT>” commands below.<BR> <BR> -<LI>On <TT>second</TT> run under `<TT>ejabberd</TT>' user in a directory - where ejabberd will work later the following command: -<PRE> +<LI CLASS="li-enumerate">On <TT>second</TT> run as the `<TT>ejabberd</TT>' user in the directory + where <TT>ejabberd</TT> will work later the following command: +<PRE CLASS="verbatim"> erl -sname ejabberd \ -mnesia extra_db_nodes "['ejabberd@first']" \ -s mnesia -</PRE>This will start mnesia serving same DB as <TT>ejabberd@first</TT>. - You can check this running ``<CODE>mnesia:info().</CODE>'' command. You +</PRE> + This will start Mnesia serving the same database as <TT>ejabberd@first</TT>. + You can check this by running the command “<CODE>mnesia:info().</CODE>”. You should see a lot of remote tables and a line like the following: -<PRE> +<PRE CLASS="verbatim"> running db nodes = [ejabberd@first, ejabberd@second] -</PRE> - -<LI>Now run the following in the same ``<TT>erl</TT>'' session: -<PRE> +</PRE><BR> +<BR> +<LI CLASS="li-enumerate">Now run the following in the same “<TT>erl</TT>” session: +<PRE CLASS="verbatim"> mnesia:change_table_copy_type(schema, node(), disc_copies). </PRE> - This will create local disc storage for DB.<BR> + This will create local disc storage for the database.<BR> <BR> -(alt) Change storage type of `<TT>scheme</TT>' table to ``RAM and disc - copy'' on second node via web interface.<BR> +(alt) Change storage type of `<TT>scheme</TT>' table to “RAM and disc + copy” on the second node via the web interface.<BR> <BR> -<LI>Now you can add replicas of various tables to this node with - ``<CODE>mnesia:add_table_copy</CODE>'' or - ``<CODE>mnesia:change_table_copy_type</CODE>'' as above (just replace - ``<CODE>schema</CODE>'' with another table name and ``<CODE>disc_copies</CODE>'' - can be replaced with ``<CODE>ram_copies</CODE>'' or - ``<CODE>disc_only_copies</CODE>'').<BR> +<LI CLASS="li-enumerate">Now you can add replicas of various tables to this node with + “<CODE>mnesia:add_table_copy</CODE>” or + “<CODE>mnesia:change_table_copy_type</CODE>” as above (just replace + “<CODE>schema</CODE>” with another table name and “<CODE>disc_copies</CODE>” + can be replaced with “<CODE>ram_copies</CODE>” or + “<CODE>disc_only_copies</CODE>”).<BR> <BR> -What tables to replicate is very depend on your needs, you can get - some hints from ``<CODE>mnesia:info().</CODE>'' command, by looking at - size of tables and default storage type for each table on 'first'.<BR> +Which tables to replicate is very dependant on your needs, you can get + some hints from the command “<CODE>mnesia:info().</CODE>”, by looking at the + size of tables and the default storage type for each table on 'first'.<BR> <BR> -Replicating of table makes lookup in this table faster on this node, - but writing will be slower. And of course if machine with one of - replicas is down, other replicas will be used.<BR> +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.<BR> <BR> -Also section 5.3 (Table Fragmentation) of - <A HREF="http://www.erlang.se/doc/doc-5.4/lib/mnesia-4.2/doc/html/index.html">Mnesia Reference Manual</A> can be useful.<BR> +Also <A HREF="http://www.erlang.se/doc/doc-5.4.9/lib/mnesia-4.2.2/doc/html/Mnesia_chap5.html#5.3">section 5.3 (Table Fragmentation) of Mnesia User's Guide</A> can be helpful. + <BR> <BR> -(alt) Same as in previous item, but for other tables.<BR> + (alt) Same as in previous item, but for other tables.<BR> <BR> -<LI>Run ``<CODE>init:stop().</CODE>'' or just ``<CODE>q().</CODE>'' to exit from - erlang shell. This probably can take some time if mnesia is not yet - transfer and process all data it needed from <TT>first</TT>.<BR> +<LI CLASS="li-enumerate">Run “<CODE>init:stop().</CODE>” or just “<CODE>q().</CODE>” 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 <TT>first</TT>.<BR> <BR> -<LI>Now run ejabberd on <TT>second</TT> with almost the same config as - on <TT>first</TT> (you probably don't need to duplicate ``<CODE>acl</CODE>'' - and ``<CODE>access</CODE>'' options --- they will be taken from +<LI CLASS="li-enumerate">Now run <TT>ejabberd</TT> on <TT>second</TT> with almost the same config as + on <TT>first</TT> (you probably don't need to duplicate “<CODE>acl</CODE>” + and “<CODE>access</CODE>” options — they will be taken from <TT>first</TT>, and <CODE>mod_muc</CODE> and <CODE>mod_irc</CODE> should be - enabled only on one machine in cluster). + enabled only on one machine in the cluster). </OL> You can repeat these steps for other machines supposed to serve this domain.<BR> <BR> <!--TOC section Built-in Modules--> -<H2><A NAME="htoc30">A</A> Built-in Modules</H2><!--SEC END --> +<H2 CLASS="section"><A NAME="htoc35">A</A> Built-in Modules</H2><!--SEC END --> <A NAME="sec:modules"></A> + <!--TOC subsection Common Options--> -<H3><A NAME="htoc31">A.1</A> Common Options</H3><!--SEC END --> +<H3 CLASS="subsection"><A NAME="htoc36">A.1</A> Common Options</H3><!--SEC END --> <A NAME="sec:modcommonopts"></A> -The following options are used by many modules, so they are described in -separate section.<BR> +The following options are used by many modules. Therefore, they are described in +this separate section.<BR> <BR> <!--TOC subsubsection <TT>iqdisc</TT>--> -<H4><A NAME="htoc32">A.1.1</A> <TT>iqdisc</TT></H4><!--SEC END --> +<H4 CLASS="subsubsection"><A NAME="htoc37">A.1.1</A> <TT>iqdisc</TT></H4><!--SEC END --> <A NAME="sec:modiqdiscoption"></A> + Many modules define handlers for processing IQ queries of different namespaces -to this server or to user (e. g. to <TT>example.org</TT> or to -<TT>user@example.org</TT>). This option defines processing discipline of +to this server or to a user (e. g. to <TT>example.org</TT> or to +<TT>user@example.org</TT>). This option defines processing discipline for these queries. Possible values are: -<DL COMPACT=compact><DT> -<B><TT>no_queue</TT></B><DD> All queries of namespace with this processing - discipline processed immediately. This also means that no other packets can - be processed until finished this. Hence this discipline is not recommended - if processing of query can take relatively long time. -<DT><B><TT>one_queue</TT></B><DD> In this case created separate queue for processing - of IQ queries of namespace with this discipline, and processing of this queue - is done in parallel with processing of other packets. This discipline is most - recommended. -<DT><B><TT>parallel</TT></B><DD> In this case for all packets with this discipline - spawned separate Erlang process, so all these packets processed in parallel. - Although spawning of Erlang process have relatively low cost, this can broke - server normal work, because Erlang emulator have limit on number of processes - (32000 by default). +<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description"> +<B><TT>no_queue</TT></B><DD CLASS="dd-description"> All queries of a namespace with this processing discipline are + processed immediately. This also means that no other packets can be processed + until this one has been completely processed. Hence this discipline is not + recommended if the processing of a query can take a relatively long time. +<DT CLASS="dt-description"><B><TT>one_queue</TT></B><DD CLASS="dd-description"> In this case a separate queue is created for the processing + of IQ queries of a namespace with this discipline. In addition, the processing + of this queue is done in parallel with that of other packets. This discipline + is most recommended. +<DT CLASS="dt-description"><B><TT>parallel</TT></B><DD CLASS="dd-description"> For every packet with this discipline a separate Erlang process + is spawned. Consequently, all these packets are processed in parallel. + Although spawning of Erlang process has a relatively low cost, this can break + the server's normal work, because the Erlang emulator has a limit on the + number of processes (32000 by default). </DL> Example: -<PRE> +<PRE CLASS="verbatim"> {modules, [ ... @@ -907,78 +1258,88 @@ Example: ... ]}. </PRE> -<!--TOC subsubsection <TT>host</TT>--> +<!--TOC subsubsection <TT>hosts</TT>--> -<H4><A NAME="htoc33">A.1.2</A> <TT>host</TT></H4><!--SEC END --> +<H4 CLASS="subsubsection"><A NAME="htoc38">A.1.2</A> <TT>hosts</TT></H4><!--SEC END --> -<A NAME="sec:modhostoption"></A> -This option explicitly defines hostname for the module which acts as a service.<BR> +<A NAME="sec:modhostsoption"></A> + +A module acting as a service can have one or more hostnames. These hostnames +can be defined with the <TT>hosts</TT> option.<BR> <BR> -Example: -<PRE> +Examples: +<UL CLASS="itemize"><LI CLASS="li-itemize"> +Serving the echo module on one domain: + <UL CLASS="itemize"><LI CLASS="li-itemize"> + <PRE CLASS="verbatim"> + {modules, + [ + ... + {mod_echo, [{hosts, ["echo.example.org"]}]}, + ... + ]}. +</PRE><LI CLASS="li-itemize">Backwards compatibility with older ejabberd versions can be retained + with: + <PRE CLASS="verbatim"> {modules, [ ... {mod_echo, [{host, "echo.example.org"}]}, ... ]}. -</PRE> -<!--TOC subsubsection <TT>hosts</TT>--> - -<H4><A NAME="htoc34">A.1.3</A> <TT>hosts</TT></H4><!--SEC END --> - -<A NAME="sec:modhostsoption"></A> -This option explicitly defines a list of hostnames for the module which acts as -a service.<BR> -<BR> -Example: -<PRE> +</PRE></UL> + <LI CLASS="li-itemize">Serving the echo module on tho domains: + <PRE CLASS="verbatim"> {modules, [ ... - {mod_echo, [{hosts, ["echo.example.org", "echo.example.com"]}]}, + {mod_echo, [{hosts, ["echo.one.org", "echo.two.org"]}]}, ... ]}. -</PRE> +</PRE></UL> <!--TOC subsection <TT>mod_announce</TT>--> -<H3><A NAME="htoc35">A.2</A> <TT>mod_announce</TT></H3><!--SEC END --> +<H3 CLASS="subsection"><A NAME="htoc39">A.2</A> <TT>mod_announce</TT></H3><!--SEC END --> <A NAME="sec:modannounce"></A> -This module adds support for broadcast announce messages and MOTD. -When the module is loaded, it handles messages sent to the following JID's -(suppose that main server has address <TT>example.org</TT>): -<DL COMPACT=compact><DT> -<B><TT>example.org/announce/all</TT></B><DD> Message is sent to all registered users at -<TT>example.org</TT>. If the user is online and connected to several resources, -only resource with the highest priority will receive the message. If the -registered user is not connected, the message will be stored offline (if -oflline storage is available). -<DT><B><TT>example.org/announce/online</TT></B><DD> Message is sent to all connected users at -<TT>example.org</TT>. If the user is online and connected to several resources, -all resources will receive the message. -<DT><B><TT>example.org/announce/all-hosts/online</TT></B><DD> Message is sent to all connected -users at every virtual host. If the user is online and connected to several -resources, all resources will receive the message. -<DT><B><TT>example.org/announce/motd</TT></B><DD> Message is set as MOTD (Message of the Day) -and is sent to users at <TT>example.org</TT> as they login. In addition the -message is sent to all connected users (similar to <TT>announce/online</TT> -resource). -<DT><B><TT>example.org/announce/motd/update</TT></B><DD> Message is set as MOTD (Message of the -Day) and is sent to users at <TT>example.org</TT> as they login. The message -is <EM>not sent</EM> to all connected users. -<DT><B><TT>example.org/announce/motd/delete</TT></B><DD> Any message sent to this JID -removes existing MOTD. + +This module enables configured users to broadcast announcements and to set +the message of the day (MOTD). Configured users can do these actions with their +Jabber client by sending messages to specific JIDs. These JIDs are listed in +next paragraph. The first JID in each entry will apply only to the virtual host +<TT>example.org</TT>, while the JID between brackets will apply to all virtual +hosts: +<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description"> +<B><TT>example.org/announce/all (example.org/announce/all-hosts/all)</TT></B><DD CLASS="dd-description"> The + message is sent to all registered users. If the user is online and connected + 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 HREF="#sec:modoffline">A.8</A>) is enabled. +<DT CLASS="dt-description"><B><TT>example.org/announce/online (example.org/announce/all-hosts/online)</TT></B><DD CLASS="dd-description">The + message is sent to all connected users. If the user is online and connected + to several resources, all resources will receive the message. +<DT CLASS="dt-description"><B><TT>example.org/announce/motd (example.org/announce/all-hosts/motd)</TT></B><DD CLASS="dd-description">The + message is set as the message of the day (MOTD) and is sent to users when they + login. In addition the message is sent to all connected users (similar to + <TT>announce/online</TT>). +<DT CLASS="dt-description"><B><TT>example.org/announce/motd/update (example.org/announce/all-hosts/motd/update)</TT></B><DD CLASS="dd-description"> + The message is set as message of the day (MOTD) and is sent to users when they + login. The message is <EM>not sent</EM> to any currently connected user. +<DT CLASS="dt-description"><B><TT>example.org/announce/motd/delete (example.org/announce/all-hosts/motd/delete)</TT></B><DD CLASS="dd-description"> + Any message sent to this JID removes the existing message of the day (MOTD). </DL> Options: -<DL COMPACT=compact><DT> -<B><TT>access</TT></B><DD> Specifies who is allowed to send announce messages -and set MOTD (default value is <TT>none</TT>). +<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description"> +<B><TT>access</TT></B><DD CLASS="dd-description"> This option specifies who is allowed to + send announcements and to set the message of the day (by default, nobody is + able to send such messages). </DL> -Example: -<PRE> - % Only admins can send announcement messages: - {access, announce, [{allow, admin}]}. +Examples: +<UL CLASS="itemize"><LI CLASS="li-itemize"> +Only administrators can send announcements: + <PRE CLASS="verbatim"> + {access, announce, [{allow, admins}]}. {modules, [ @@ -986,191 +1347,380 @@ Example: {mod_announce, [{access, announce}]}, ... ]}. -</PRE> -<!--TOC subsection <TT>mod_configure</TT>--> - -<H3><A NAME="htoc36">A.3</A> <TT>mod_configure</TT></H3><!--SEC END --> - -<A NAME="sec:modconfigure"></A> -Options: -<DL COMPACT=compact><DT> -<B><TT>iqdisc</TT></B><DD> <TT>ejabberd:config</TT> IQ queries processing -discipline (see <A HREF="#sec:modiqdiscoption">A.1.1</A>). -</DL> +</PRE><LI CLASS="li-itemize">Administrators as well as the direction can send announcements: + <PRE CLASS="verbatim"> + {acl, direction, {user, "big_boss", "example.org"}}. + {acl, direction, {user, "assistant", "example.org"}}. + {acl, admins, {user, "admin", "example.org"}}. + ... + {access, announce, [{allow, admins}, + {allow, direction}]}. + ... + {modules, + [ + ... + {mod_announce, [{access, announce}]}, + ... + ]}. +</PRE></UL> <!--TOC subsection <TT>mod_disco</TT>--> -<H3><A NAME="htoc37">A.4</A> <TT>mod_disco</TT></H3><!--SEC END --> +<H3 CLASS="subsection"><A NAME="htoc40">A.3</A> <TT>mod_disco</TT></H3><!--SEC END --> <A NAME="sec:moddisco"></A> -This module adds support for <A HREF="http://www.jabber.org/jeps/jep-0030.html">JEP-0030</A> (Service Discovery).<BR> + +This module adds support for Service Discovery (<A HREF="http://www.jabber.org/jeps/jep-0030.html">JEP-0030</A>). With +this module enabled, services on your server can be discovered by +Jabber clients. Note that <TT>ejabberd</TT> has no modules with support +for the superseded Jabber Browsing (<A HREF="http://www.jabber.org/jeps/jep-0011.html">JEP-0011</A>) and Agent Information +(<A HREF="http://www.jabber.org/jeps/jep-0094.html">JEP-0094</A>). Accordingly, Jabber clients need to have support for +the newer Service Discovery protocol if you want them be able to discover +the services you offer.<BR> <BR> Options: -<DL COMPACT=compact><DT> -<B><TT>iqdisc</TT></B><DD> <TT>http://jabber.org/protocol/disco#items</TT> and - <TT>http://jabber.org/protocol/disco#info</TT> IQ queries processing -discipline (see <A HREF="#sec:modiqdiscoption">A.1.1</A>). -<DT><B><TT>extra_domains</TT></B><DD> List of domains that will be added to server - items reply +<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description"> +<B><TT>iqdisc</TT></B><DD CLASS="dd-description"> This specifies +the processing discipline for Service Discovery (<TT>http://jabber.org/protocol/disco#items</TT> and + <TT>http://jabber.org/protocol/disco#info</TT>) IQ queries +(see section <A HREF="#sec:modiqdiscoption">A.1.1</A>). +<DT CLASS="dt-description"><B><TT>extra_domains</TT></B><DD CLASS="dd-description"> With this option, + extra domains can be added to the Service Discovery item list. </DL> -Example: -<PRE> +Examples: +<UL CLASS="itemize"><LI CLASS="li-itemize"> +To serve a link to the Jabber User Directory on <TT>jabber.org</TT>: + <PRE CLASS="verbatim"> {modules, [ ... - {mod_disco, [{extra_domains, ["jit.example.com", - "etc.example.com"]}]}, + {mod_disco, [{extra_domains, ["users.jabber.org"]}]}, ... ]}. -</PRE> +</PRE><LI CLASS="li-itemize">To serve a link to the transports on another server: + <PRE CLASS="verbatim"> + {modules, + [ + ... + {mod_disco, [{extra_domains, ["icq.example.com", + "msn.example.com"]}]}, + ... + ]}. +</PRE><LI CLASS="li-itemize">To serve a link to a few friendly servers: + <PRE CLASS="verbatim"> + {modules, + [ + ... + {mod_disco, [{extra_domains, ["example.org", + "example.com"]}]}, + ... + ]}. +</PRE></UL> <!--TOC subsection <TT>mod_echo</TT>--> -<H3><A NAME="htoc38">A.5</A> <TT>mod_echo</TT></H3><!--SEC END --> +<H3 CLASS="subsection"><A NAME="htoc41">A.4</A> <TT>mod_echo</TT></H3><!--SEC END --> <A NAME="sec:modecho"></A> -This module acts as a service and simply returns to sender any Jabber -packet. Module may be useful for debugging.<BR> + +This module simply echoes any Jabber +packet back to the sender. This mirror can be of interest for +<TT>ejabberd</TT> and Jabber client debugging.<BR> <BR> Options: -<DL COMPACT=compact><DT> +<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description"> - <B><TT>host</TT></B><DD> Defines hostname of the service - (see <A HREF="#sec:modhostoption">A.1.2</A>). - <DT><B><TT>hosts</TT></B><DD> Defines hostnames of the service - (see <A HREF="#sec:modhostsoption">A.1.3</A>). If neither <TT>host</TT> nor <TT>hosts</TT> - are not present, then prefix <TT>echo.</TT> is added to all <TT>ejabberd</TT> hostnames. + <B><TT>hosts</TT></B><DD CLASS="dd-description"> This option defines the hostnames of the + service (see section <A HREF="#sec:modhostsoption">A.1.2</A>). If neither <TT>hosts</TT> nor + the old <TT>host</TT> is present, the prefix “<TT>echo.</TT>” is added to all + <TT>ejabberd</TT> hostnames. </DL> +Examples: +<UL CLASS="itemize"><LI CLASS="li-itemize"> +Mirror, mirror, on the wall, who is the most beautiful + of them all? + <PRE CLASS="verbatim"> + {modules, + [ + ... + {mod_echo, [{hosts, ["mirror.example.org"]}]}, + ... + ]}. +</PRE><LI CLASS="li-itemize">If you still do not understand the inner workings of <TT>mod_echo</TT>, + you can find a few more examples in section <A HREF="#sec:modhostsoption">A.1.2</A>. +</UL> <!--TOC subsection <TT>mod_irc</TT>--> -<H3><A NAME="htoc39">A.6</A> <TT>mod_irc</TT></H3><!--SEC END --> +<H3 CLASS="subsection"><A NAME="htoc42">A.5</A> <TT>mod_irc</TT></H3><!--SEC END --> <A NAME="sec:modirc"></A> -This module implements IRC transport.<BR> + +This module is an IRC transport that can be used to join channels on IRC +servers.<BR> <BR> +End user information: + +<UL CLASS="itemize"><LI CLASS="li-itemize"> +A Jabber client with “groupchat 1.0” support or Multi-User + Chat support (<A HREF="http://www.jabber.org/jeps/jep-0045.html">JEP-0045</A>) is necessary to join IRC channels. +<LI CLASS="li-itemize">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%<TT>irc.example.org</TT>” in case <TT>irc.example.org</TT> is + the IRC server hosting “channel”. And of course the host should point + to the IRC transport instead of the Multi-User Chat service. +<LI CLASS="li-itemize">You can register your nickame by sending “IDENTIFY password” to<BR> +<TT>nickserver!irc.example.org@irc.jabberserver.org</TT>. +<LI CLASS="li-itemize">Entering your password is possible by sending “LOGIN nick password”<BR> +to <TT>nickserver!irc.example.org@irc.jabberserver.org</TT>. +<LI CLASS="li-itemize">When using a popular Jabber server, it can occur that no + connection can be achieved with some IRC servers because they limit the + number of conections from one IP. +</UL> Options: -<DL COMPACT=compact><DT> +<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description"> - <B><TT>host</TT></B><DD> Defines hostname of the service - (see <A HREF="#sec:modhostoption">A.1.2</A>). - <DT><B><TT>hosts</TT></B><DD> Defines hostnames of the service - (see <A HREF="#sec:modhostsoption">A.1.3</A>). If neither <TT>host</TT> nor <TT>hosts</TT> - are not present, then prefix <TT>irc.</TT> is added to all <TT>ejabberd</TT> hostnames. + <B><TT>hosts</TT></B><DD CLASS="dd-description"> This option defines the hostnames of the + service (see section <A HREF="#sec:modhostsoption">A.1.2</A>). If neither <TT>hosts</TT> nor + the old <TT>host</TT> is present, the prefix “<TT>irc.</TT>” is added to all + <TT>ejabberd</TT> hostnames. -<DT><B><TT>access</TT></B><DD> Specifies who is allowed to use IRC transport (default value is <TT>all</TT>). +<DT CLASS="dt-description"><B><TT>access</TT></B><DD CLASS="dd-description"> This option can be used to specify who + may use the IRC transport (default value: <TT>all</TT>). </DL> -Example: -<PRE> +Examples: +<UL CLASS="itemize"><LI CLASS="li-itemize"> +In the first example, the IRC transport is available on (all) your + virtual host(s) with the prefix “<TT>irc.</TT>”. Furthermore, anyone is + able to use the transport. + <PRE CLASS="verbatim"> {modules, [ ... {mod_irc, [{access, all}]}, ... ]}. -</PRE> +</PRE><LI CLASS="li-itemize">In next example the IRC transport is available on two virtual hosts + with different prefixes on each host. Moreover, the transport is only + accessible by paying customers registered on our domains and on other servers. + <PRE CLASS="verbatim"> + {acl, paying_customers, {user, "customer1", "one.org"}}. + {acl, paying_customers, {user, "customer2", "two.org"}}. + {acl, paying_customers, {user, "customer3", "example.org"}}. + ... + {access, paying_customers, [{allow, paying_customers}, + {deny, all}]}. + ... + {modules, + [ + ... + {mod_irc, [{access, paying_customers}, + {hosts, ["irc.one.org", "irc-transport.two.org"]}]}, + ... + ]}. +</PRE></UL> <!--TOC subsection <TT>mod_last</TT>--> -<H3><A NAME="htoc40">A.7</A> <TT>mod_last</TT></H3><!--SEC END --> +<H3 CLASS="subsection"><A NAME="htoc43">A.6</A> <TT>mod_last</TT></H3><!--SEC END --> <A NAME="sec:modlast"></A> -This module adds support for <A HREF="http://www.jabber.org/jeps/jep-0012.html">JEP-0012</A> (Last Activity)<BR> + +This module adds support for Last Activity (<A HREF="http://www.jabber.org/jeps/jep-0012.html">JEP-0012</A>). It can be used to +discover when a disconnected user last accessed the server, to know when a +connected user was last active on the server, or to query the uptime of the +<TT>ejabberd</TT> server.<BR> <BR> Options: -<DL COMPACT=compact><DT> -<B><TT>iqdisc</TT></B><DD> <TT>jabber:iq:last</TT> IQ queries processing -discipline (see <A HREF="#sec:modiqdiscoption">A.1.1</A>). +<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description"> +<B><TT>iqdisc</TT></B><DD CLASS="dd-description"> This specifies +the processing discipline for Last activity (<TT>jabber:iq:last</TT>) IQ queries +(see section <A HREF="#sec:modiqdiscoption">A.1.1</A>). </DL> <!--TOC subsection <TT>mod_muc</TT>--> -<H3><A NAME="htoc41">A.8</A> <TT>mod_muc</TT></H3><!--SEC END --> +<H3 CLASS="subsection"><A NAME="htoc44">A.7</A> <TT>mod_muc</TT></H3><!--SEC END --> <A NAME="sec:modmuc"></A> -This module implements <A HREF="http://www.jabber.org/jeps/jep-0045.html">JEP-0045</A> (Multi-User Chat) service.<BR> + +With this module enabled, your server will support Multi-User Chat +(<A HREF="http://www.jabber.org/jeps/jep-0045.html">JEP-0045</A>). End users will be able to join text conferences. Notice +that this module is not (yet) clusterable.<BR> <BR> +Some of the features of Multi-User Chat: +<UL CLASS="itemize"><LI CLASS="li-itemize"> +Sending private messages to room participants. +<LI CLASS="li-itemize">Inviting users. +<LI CLASS="li-itemize">Setting a conference topic. +<LI CLASS="li-itemize">Creating password protected rooms. +<LI CLASS="li-itemize">Kicking and banning participants. +</UL> Options: -<DL COMPACT=compact><DT> - - <B><TT>host</TT></B><DD> Defines hostname of the service - (see <A HREF="#sec:modhostoption">A.1.2</A>). - <DT><B><TT>hosts</TT></B><DD> Defines hostnames of the service - (see <A HREF="#sec:modhostsoption">A.1.3</A>). If neither <TT>host</TT> nor <TT>hosts</TT> - are not present, then prefix <TT>conference.</TT> is added to all <TT>ejabberd</TT> hostnames. - -<DT><B><TT>access</TT></B><DD> Specifies who is allowed to use MUC service (default value is <TT>all</TT>). -<DT><B><TT>access_create</TT></B><DD> Specifies who is allowed to create new rooms at - MUC service (default value is <TT>all</TT>). -<DT><B><TT>access_admin</TT></B><DD> Specifies who is allowed to administrate MUC service -(default value is <TT>none</TT>, which means that only creator may administer her room). +<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description"> + + <B><TT>hosts</TT></B><DD CLASS="dd-description"> This option defines the hostnames of the + service (see section <A HREF="#sec:modhostsoption">A.1.2</A>). If neither <TT>hosts</TT> nor + the old <TT>host</TT> is present, the prefix “<TT>conference.</TT>” is added to all + <TT>ejabberd</TT> hostnames. + +<DT CLASS="dt-description"><B><TT>access</TT></B><DD CLASS="dd-description"> You can specify who is allowed to use + the Multi-User Chat service (by default, everyone is allowed to use it). +<DT CLASS="dt-description"><B><TT>access_create</TT></B><DD CLASS="dd-description"> To configure who is + allowed to create new rooms at the Multi-User Chat service, this option + can be used (by default, everybody is allowed to create rooms). +<DT CLASS="dt-description"><B><TT>access_admin</TT></B><DD CLASS="dd-description"> This option specifies + who is allowed to administrate the Multi-User Chat service (the default + value is <TT>none</TT>, which means that only the room creator can + administer his room). </DL> -Example: -<PRE> - % Define admin ACL - {acl, admin, {user, "admin"}} - - % Define MUC admin access rule - {access, muc_admin, [{allow, admin}]} - +Examples: +<UL CLASS="itemize"><LI CLASS="li-itemize"> +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 + <TT>admin@example.org</TT> is allowed to administrate any room. In this + example he is also a global administrator. + <PRE CLASS="verbatim"> + {acl, admins, {user, "admin", "example.org"}}. + ... + {access, muc_admins, [{allow, admins}]}. + ... {modules, [ ... {mod_muc, [{access, all}, {access_create, all}, - {access_admin, muc_admin}]}, + {access_admin, muc_admins}]}, ... ]}. -</PRE> +</PRE><LI CLASS="li-itemize">In the second example the Multi-User Chat service is only accessible by + 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. + <PRE CLASS="verbatim"> + {acl, paying_customers, {user, "customer1", "one.org"}}. + {acl, paying_customers, {user, "customer2", "two.org"}}. + {acl, paying_customers, {user, "customer3", "example.org"}}. + {acl, admins, {user, "admin", "example.org"}}. + ... + {access, muc_admins, [{allow, admins}, + {deny, all}]}. + {access, muc_access, [{allow, paying_customers}, + {allow, admins}, + {deny, all}]}. + ... + {modules, + [ + ... + {mod_muc, [{access, muc_access}, + {access_create, muc_admins}, + {access_admin, muc_admins}]}, + ... + ]}. +</PRE></UL> <!--TOC subsection <TT>mod_offline</TT>--> -<H3><A NAME="htoc42">A.9</A> <TT>mod_offline</TT></H3><!--SEC END --> +<H3 CLASS="subsection"><A NAME="htoc45">A.8</A> <TT>mod_offline</TT></H3><!--SEC END --> <A NAME="sec:modoffline"></A> -This module implements offline message storage.<BR> + +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 +<TT>ejabberdctl</TT> has a command to delete expired messages +(see section <A HREF="#sec:ejabberdctl">3.3.2</A>).<BR> <BR> <!--TOC subsection <TT>mod_privacy</TT>--> -<H3><A NAME="htoc43">A.10</A> <TT>mod_privacy</TT></H3><!--SEC END --> +<H3 CLASS="subsection"><A NAME="htoc46">A.9</A> <TT>mod_privacy</TT></H3><!--SEC END --> <A NAME="sec:modprivacy"></A> -This module implements Privacy Rules as defined in XMPP IM -(see <A HREF="http://www.jabber.org/ietf/"><TT>http://www.jabber.org/ietf/</TT></A>).<BR> -<BR> + +This module implements Blocking Communication (also known as Privacy Rules) +as defined in section 10 from XMPP IM. If end users have support for it in +their Jabber client, they will be able to: +<BLOCKQUOTE CLASS="quote"> +<UL CLASS="itemize"><LI CLASS="li-itemize"> +Retrieving one's privacy lists. +<LI CLASS="li-itemize">Adding, removing, and editing one's privacy lists. +<LI CLASS="li-itemize">Setting, changing, or declining active lists. +<LI CLASS="li-itemize">Setting, changing, or declining the default list (i.e., the list that + is active by default). +<LI CLASS="li-itemize">Allowing or blocking messages based on JID, group, or subscription type + (or globally). +<LI CLASS="li-itemize">Allowing or blocking inbound presence notifications based on JID, group, + or subscription type (or globally). +<LI CLASS="li-itemize">Allowing or blocking outbound presence notifications based on JID, group, + or subscription type (or globally). +<LI CLASS="li-itemize">Allowing or blocking IQ stanzas based on JID, group, or subscription type + (or globally). +<LI CLASS="li-itemize">Allowing or blocking all communications based on JID, group, or + subscription type (or globally). +</UL> +(from <A HREF="http://www.xmpp.org/specs/rfc3921.html#privacy"><TT>http://www.xmpp.org/specs/rfc3921.html#privacy</TT></A>) +</BLOCKQUOTE> Options: -<DL COMPACT=compact><DT> -<B><TT>iqdisc</TT></B><DD> <TT>jabber:iq:privacy</TT> IQ queries processing -discipline (see <A HREF="#sec:modiqdiscoption">A.1.1</A>). +<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description"> +<B><TT>iqdisc</TT></B><DD CLASS="dd-description"> This specifies +the processing discipline for Blocking Communication (<TT>jabber:iq:privacy</TT>) IQ queries +(see section <A HREF="#sec:modiqdiscoption">A.1.1</A>). </DL> <!--TOC subsection <TT>mod_private</TT>--> -<H3><A NAME="htoc44">A.11</A> <TT>mod_private</TT></H3><!--SEC END --> +<H3 CLASS="subsection"><A NAME="htoc47">A.10</A> <TT>mod_private</TT></H3><!--SEC END --> <A NAME="sec:modprivate"></A> -This module adds support of <A HREF="http://www.jabber.org/jeps/jep-0049.html">JEP-0049</A> (Private XML Storage).<BR> -<BR> + +This module adds support for Private XML Storage (<A HREF="http://www.jabber.org/jeps/jep-0049.html">JEP-0049</A>): +<BLOCKQUOTE CLASS="quote"> +Using this method, Jabber entities can store private data on the server and +retrieve it whenever necessary. The data stored might be anything, as long as +it is valid XML. One typical usage for this namespace is the server-side storage +of client-specific preferences; another is Bookmark Storage (<A HREF="http://www.jabber.org/jeps/jep-0048.html">JEP-0048</A>). +</BLOCKQUOTE> Options: -<DL COMPACT=compact><DT> -<B><TT>iqdisc</TT></B><DD> <TT>jabber:iq:private</TT> IQ queries processing -discipline (see <A HREF="#sec:modiqdiscoption">A.1.1</A>). +<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description"> +<B><TT>iqdisc</TT></B><DD CLASS="dd-description"> This specifies +the processing discipline for Private XML Storage (<TT>jabber:iq:private</TT>) IQ queries +(see section <A HREF="#sec:modiqdiscoption">A.1.1</A>). </DL> <!--TOC subsection <TT>mod_pubsub</TT>--> -<H3><A NAME="htoc45">A.12</A> <TT>mod_pubsub</TT></H3><!--SEC END --> +<H3 CLASS="subsection"><A NAME="htoc48">A.11</A> <TT>mod_pubsub</TT></H3><!--SEC END --> <A NAME="sec:modpubsub"></A> -This module implements <A HREF="http://www.jabber.org/jeps/jep-0060.html">JEP-0060</A> (Publish-Subscribe Service).<BR> + +This module offers a Publish-Subscribe Service (<A HREF="http://www.jabber.org/jeps/jep-0060.html">JEP-0060</A>). +Publish-Subscribe can be used to develop (examples are taken from the JEP): +<BLOCKQUOTE CLASS="quote"> +<UL CLASS="itemize"><LI CLASS="li-itemize"> +news feeds and content syndacation, +<LI CLASS="li-itemize">avatar management, +<LI CLASS="li-itemize">shared bookmarks, +<LI CLASS="li-itemize">auction and trading systems, +<LI CLASS="li-itemize">online catalogs, +<LI CLASS="li-itemize">workflow systems, +<LI CLASS="li-itemize">network management systems, +<LI CLASS="li-itemize">NNTP gateways, +<LI CLASS="li-itemize">vCard/profile management, +<LI CLASS="li-itemize">and weblogs. +</UL> +</BLOCKQUOTE> + +Another example is <A HREF="http://www.process-one.net/en/projects/j-eai/">J-EAI</A>. +This is an XMPP-based Enterprise Application Integration (EAI) platform (also +known as ESB, the Enterprise Service Bus). The J-EAI project builts upon +<TT>ejabberd</TT>'s codebase and has contributed several features to <TT>mod_pubsub</TT>.<BR> <BR> Options: -<DL COMPACT=compact><DT> +<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description"> - <B><TT>host</TT></B><DD> Defines hostname of the service - (see <A HREF="#sec:modhostoption">A.1.2</A>). - <DT><B><TT>hosts</TT></B><DD> Defines hostnames of the service - (see <A HREF="#sec:modhostsoption">A.1.3</A>). If neither <TT>host</TT> nor <TT>hosts</TT> - are not present, then prefix <TT>pubsub.</TT> is added to all <TT>ejabberd</TT> hostnames. + <B><TT>hosts</TT></B><DD CLASS="dd-description"> This option defines the hostnames of the + service (see section <A HREF="#sec:modhostsoption">A.1.2</A>). If neither <TT>hosts</TT> nor + the old <TT>host</TT> is present, the prefix “<TT>pubsub.</TT>” is added to all + <TT>ejabberd</TT> hostnames. -<DT><B><TT>served_hosts</TT></B><DD> Specifies which hosts are served by the service. -If absent then only main <TT>ejabberd</TT> host is served. -</DL> +<DT CLASS="dt-description"><B><TT>served_hosts</TT></B><DD CLASS="dd-description"> To specify which hosts needs to + be served, you can use this option. If absent, only the main <TT>ejabberd</TT> + host is served. </DL> Example: -<PRE> +<PRE CLASS="verbatim"> {modules, [ ... @@ -1181,131 +1731,187 @@ Example: </PRE> <!--TOC subsection <TT>mod_register</TT>--> -<H3><A NAME="htoc46">A.13</A> <TT>mod_register</TT></H3><!--SEC END --> +<H3 CLASS="subsection"><A NAME="htoc49">A.12</A> <TT>mod_register</TT></H3><!--SEC END --> <A NAME="sec:modregister"></A> -This module adds support for <A HREF="http://www.jabber.org/jeps/jep-0077.html">JEP-0077</A> (In-Band Registration).<BR> -<BR> + +This module adds support for In-Band Registration (<A HREF="http://www.jabber.org/jeps/jep-0077.html">JEP-0077</A>). This protocol +enables end users to use a Jabber client to: +<UL CLASS="itemize"><LI CLASS="li-itemize"> +Register a new account on the server. +<LI CLASS="li-itemize">Change the password from an existing account on the server. +<LI CLASS="li-itemize">Delete an existing account on the server. +</UL> Options: -<DL COMPACT=compact><DT> -<B><TT>access</TT></B><DD> Specifies rule to restrict registration. -If this rule returns ``deny'' on requested user name, then -registration is not allowed for it. (default value is <TT>all</TT>, which means -no restrictions). -<DT><B><TT>iqdisc</TT></B><DD> <TT>jabber:iq:register</TT> IQ queries processing -discipline (see <A HREF="#sec:modiqdiscoption">A.1.1</A>). +<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description"> +<B><TT>access</TT></B><DD CLASS="dd-description"> This option can be configured to specify + 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). +<DT CLASS="dt-description"><B><TT>iqdisc</TT></B><DD CLASS="dd-description"> This specifies +the processing discipline for In-Band Registration (<TT>jabber:iq:register</TT>) IQ queries +(see section <A HREF="#sec:modiqdiscoption">A.1.1</A>). </DL> -Example: -<PRE> - % Deny registration for users with too short name +Examples: +<UL CLASS="itemize"><LI CLASS="li-itemize"> +Next example prohibits the registration of too short account names and of + account names with exotic characters in it: + <PRE CLASS="verbatim"> {acl, shortname, {user_glob, "?"}}. {acl, shortname, {user_glob, "??"}}. - % Another variant: {acl, shortname, {user_regexp, "^..?$"}}. - + {acl, strangename, {user_regexp, "^..?$"}}. + ... {access, register, [{deny, shortname}, + {deny, strangename}, {allow, all}]}. - + ... {modules, [ ... {mod_register, [{access, register}]}, ... ]}. -</PRE> +</PRE><LI CLASS="li-itemize">The in-band registration of new accounts can be prohibited by changing the + <TT>access</TT> option. If you really want to disable all In-Band Registration + functionality, that is changing passwords in-band and deleting accounts + in-band, you have to remove <TT>mod_register</TT> from the modules list. In this + example all In-Band Registration functionality is disabled: + <PRE CLASS="verbatim"> + {access, register, [{deny, all}]}. + + {modules, + [ + ... +% {mod_register, [{access, register}]}, + ... + ]}. +</PRE></UL> <!--TOC subsection <TT>mod_roster</TT>--> -<H3><A NAME="htoc47">A.14</A> <TT>mod_roster</TT></H3><!--SEC END --> +<H3 CLASS="subsection"><A NAME="htoc50">A.13</A> <TT>mod_roster</TT></H3><!--SEC END --> <A NAME="sec:modroster"></A> -This module implements roster management.<BR> + +This module implements roster management as defined in <A HREF="http://www.xmpp.org/specs/rfc3921.html#roster">RFC 3921: XMPP IM</A>.<BR> <BR> Options: -<DL COMPACT=compact><DT> -<B><TT>iqdisc</TT></B><DD> <TT>jabber:iq:roster</TT> IQ queries processing -discipline (see <A HREF="#sec:modiqdiscoption">A.1.1</A>). +<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description"> +<B><TT>iqdisc</TT></B><DD CLASS="dd-description"> This specifies +the processing discipline for Roster Management (<TT>jabber:iq:roster</TT>) IQ queries +(see section <A HREF="#sec:modiqdiscoption">A.1.1</A>). </DL> <!--TOC subsection <TT>mod_service_log</TT>--> -<H3><A NAME="htoc48">A.15</A> <TT>mod_service_log</TT></H3><!--SEC END --> +<H3 CLASS="subsection"><A NAME="htoc51">A.14</A> <TT>mod_service_log</TT></H3><!--SEC END --> <A NAME="sec:modservicelog"></A> -This module adds support for logging of user packets via any jabber service. -These packets encapsulated in <route/> element and sended to specified -services.<BR> + +This module adds support for logging end user packets via a Jabber message +auditing service such as +<A HREF="http://www.funkypenguin.co.za/bandersnatch/">Bandersnatch</A>. All user +packets are encapsulated in a <CODE><route/></CODE> element and sent to the specified +service(s).<BR> <BR> Options: -<DL COMPACT=compact><DT> - <B><TT>loggers</TT></B><DD> Specifies a list of services which will receive users - packets. +<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description"> +<B><TT>loggers</TT></B><DD CLASS="dd-description"> With this option a (list of) service(s) + that will receive the packets can be specified. </DL> -Example: -<PRE> +Examples: +<UL CLASS="itemize"><LI CLASS="li-itemize"> +To log all end user packets to the Bandersnatch service running on + <TT>bandersnatch.example.com</TT>: + <PRE CLASS="verbatim"> {modules, [ ... {mod_service_log, [{loggers, ["bandersnatch.example.com"]}]}, ... ]}. -</PRE> +</PRE><LI CLASS="li-itemize">To log all end user packets to the Bandersnatch service running on + <TT>bandersnatch.example.com</TT> and the backup service on + <TT>bandersnatch.example.org</TT>: + <PRE CLASS="verbatim"> + {modules, + [ + ... + {mod_service_log, [{loggers, ["bandersnatch.example.com", + "bandersnatch.example.org"]}]}, + ... + ]}. +</PRE></UL> <!--TOC subsection <TT>mod_shared_roster</TT>--> -<H3><A NAME="htoc49">A.16</A> <TT>mod_shared_roster</TT></H3><!--SEC END --> +<H3 CLASS="subsection"><A NAME="htoc52">A.15</A> <TT>mod_shared_roster</TT></H3><!--SEC END --> <A NAME="sec:modsharedroster"></A> -This module implements shared roster groups support.<BR> -<BR> -You can edit shared roster groups via web-interface. Each group has an unique -ID and the following parameters: -<DL COMPACT=compact><DT> -<B>Name</B><DD> The name of the group, which will be displayed in roster. -<DT><B>Description</B><DD> Textual description of this group, doesn't affect anything. -<DT><B>Members</B><DD> List of full JIDs of group members, entered one per line in - web-interface. -<DT><B>Displayed groups</B><DD> List of IDs of groups which will be in rosters of this - group members. + +This module enables you to create shared roster groups. This means that you can +create groups of people that can see members from (other) groups in their +rosters. The big advantages of this feature are that end users do not need to +manually add all users to their rosters, and that they cannot permanently delete +users from the shared roster groups.<BR> +<BR> +Shared roster groups can be edited <EM>only</EM> via the web interface. Each group +has a unique identification and the following parameters: +<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description"> +<B>Name</B><DD CLASS="dd-description"> The name of the group, which will be displayed in the roster. +<DT CLASS="dt-description"><B>Description</B><DD CLASS="dd-description"> The description of the group. This parameter doesn't affect + anything. +<DT CLASS="dt-description"><B>Members</B><DD CLASS="dd-description"> A list of full JIDs of group members, entered one per line in + the web interface. +<DT CLASS="dt-description"><B>Displayed groups</B><DD CLASS="dd-description"> A list of groups that will be in the rosters of this + group's members. </DL> -For example, to have a group of users which can see each other in roster, -create a group like on table <A HREF="#tab:srge1">1</A>. -<BLOCKQUOTE><DIV ALIGN=center><DIV ALIGN=center><HR WIDTH="80%" SIZE=2></DIV> +Examples: +<UL CLASS="itemize"><LI CLASS="li-itemize"> +Take the case of a computer club that wants all its members seeing each + other in their rosters. To achieve this, they need to create a shared roster + group similar to next table: +<BLOCKQUOTE CLASS="table"><DIV CLASS="center"><DIV CLASS="center"><HR WIDTH="80%" SIZE=2></DIV> <TABLE BORDER=1 CELLSPACING=0 CELLPADDING=1> -<TR><TD ALIGN=left NOWRAP> </TD> -<TD ALIGN=left NOWRAP>Group `<TT>users</TT>'</TD> +<TR><TD ALIGN=left NOWRAP>Identification</TD> +<TD ALIGN=left NOWRAP>Group `<TT>club_members</TT>'</TD> </TR> <TR><TD ALIGN=left NOWRAP>Name</TD> -<TD ALIGN=left NOWRAP>Users</TD> +<TD ALIGN=left NOWRAP>Club Members</TD> +</TR> +<TR><TD ALIGN=left NOWRAP>Description</TD> +<TD ALIGN=left NOWRAP>Members from the computer club</TD> </TR> <TR><TD ALIGN=left NOWRAP>Members</TD> <TD ALIGN=left NOWRAP><TABLE CELLSPACING=2 CELLPADDING=0> -<TR><TD ALIGN=left NOWRAP><TT>user1@example.org</TT></TD> +<TR><TD ALIGN=left NOWRAP><TT>member1@example.org</TT></TD> </TR> -<TR><TD ALIGN=left NOWRAP><TT>user2@example.org</TT></TD> +<TR><TD ALIGN=left NOWRAP><TT>member2@example.org</TT></TD> </TR> -<TR><TD ALIGN=left NOWRAP><TT>user3@example.org</TT></TD> +<TR><TD ALIGN=left NOWRAP><TT>member3@example.org</TT></TD> </TR></TABLE></TD> </TR> <TR><TD ALIGN=left NOWRAP>Displayed groups</TD> -<TD ALIGN=left NOWRAP><TT>users</TT></TD> +<TD ALIGN=left NOWRAP><TT>club_members</TT></TD> </TR></TABLE> - <BR> -<DIV ALIGN=center>Table 1: Shared group example N1</DIV><BR> - - <A NAME="tab:srge1"></A> -<DIV ALIGN=center><HR WIDTH="80%" SIZE=2></DIV></DIV></BLOCKQUOTE> -To have 3 groups `<TT>managers</TT>', `<TT>workgroup1</TT>', and -`<TT>workgroup2</TT>', where group `<TT>managers</TT>' can see members of all -groups, and other two groups can see `<TT>managers</TT>' group and themselves, -create groups like on table <A HREF="#tab:srge2">2</A>. -<BLOCKQUOTE><DIV ALIGN=center><DIV ALIGN=center><HR WIDTH="80%" SIZE=2></DIV> +<DIV CLASS="center"><HR WIDTH="80%" SIZE=2></DIV></DIV></BLOCKQUOTE> +<LI CLASS="li-itemize">In another case we have a company which has three divisions: Management, + Marketing and Sales. All group members should see all other members in their + rosters. Additonally, all managers should have all marketing and sales people + in their roster. Simultaneously, all marketeers and the whole sales team + should see all managers. This scenario can be achieved by creating shared + roster groups as shown in the following table: +<BLOCKQUOTE CLASS="table"><DIV CLASS="center"><DIV CLASS="center"><HR WIDTH="80%" SIZE=2></DIV> <TABLE BORDER=1 CELLSPACING=0 CELLPADDING=1> -<TR><TD ALIGN=left NOWRAP> </TD> -<TD ALIGN=left NOWRAP>Group `<TT>managers</TT>'</TD> -<TD ALIGN=left NOWRAP>Group `<TT>workgroup1</TT>'</TD> -<TD ALIGN=left NOWRAP>Group `<TT>workgroup2</TT>'</TD> +<TR><TD ALIGN=left NOWRAP>Identification</TD> +<TD ALIGN=left NOWRAP>Group `<TT>management</TT>'</TD> +<TD ALIGN=left NOWRAP>Group `<TT>marketing</TT>'</TD> +<TD ALIGN=left NOWRAP>Group `<TT>sales</TT>'</TD> </TR> <TR><TD ALIGN=left NOWRAP>Name</TD> -<TD ALIGN=left NOWRAP>Managers</TD> -<TD ALIGN=left NOWRAP>Workgroup1</TD> -<TD ALIGN=left NOWRAP>Workgroup2</TD> +<TD ALIGN=left NOWRAP>Management</TD> +<TD ALIGN=left NOWRAP>Marketing</TD> +<TD ALIGN=left NOWRAP>Sales</TD> +</TR> +<TR><TD ALIGN=left NOWRAP>Description</TD> +<TD ALIGN=left NOWRAP> </TD> </TR> <TR><TD ALIGN=left NOWRAP>Members</TD> <TD ALIGN=left NOWRAP><TABLE CELLSPACING=2 CELLPADDING=0> @@ -1314,136 +1920,200 @@ create groups like on table <A HREF="#tab:srge2">2</A>. <TR><TD ALIGN=left NOWRAP><TT>manager2@example.org</TT></TD> </TR> <TR><TD ALIGN=left NOWRAP><TT>manager3@example.org</TT></TD> +</TR> +<TR><TD ALIGN=left NOWRAP><TT>manager4@example.org</TT></TD> </TR></TABLE> </TD> <TD ALIGN=left NOWRAP><TABLE CELLSPACING=2 CELLPADDING=0> -<TR><TD ALIGN=left NOWRAP><TT>user1@example.org</TT></TD> +<TR><TD ALIGN=left NOWRAP><TT>marketeer1@example.org</TT></TD> +</TR> +<TR><TD ALIGN=left NOWRAP><TT>marketeer2@example.org</TT></TD> </TR> -<TR><TD ALIGN=left NOWRAP><TT>user2@example.org</TT></TD> +<TR><TD ALIGN=left NOWRAP><TT>marketeer3@example.org</TT></TD> </TR> -<TR><TD ALIGN=left NOWRAP><TT>user3@example.org</TT></TD> +<TR><TD ALIGN=left NOWRAP><TT>marketeer4@example.org</TT></TD> </TR></TABLE> </TD> <TD ALIGN=left NOWRAP><TABLE CELLSPACING=2 CELLPADDING=0> -<TR><TD ALIGN=left NOWRAP><TT>user4@example.org</TT></TD> +<TR><TD ALIGN=left NOWRAP><TT>saleswoman1@example.org</TT></TD> +</TR> +<TR><TD ALIGN=left NOWRAP><TT>salesman1@example.org</TT></TD> </TR> -<TR><TD ALIGN=left NOWRAP><TT>user5@example.org</TT></TD> +<TR><TD ALIGN=left NOWRAP><TT>saleswoman2@example.org</TT></TD> </TR> -<TR><TD ALIGN=left NOWRAP><TT>user6@example.org</TT></TD> +<TR><TD ALIGN=left NOWRAP><TT>salesman2@example.org</TT></TD> </TR></TABLE></TD> </TR> <TR><TD ALIGN=left NOWRAP>Displayed groups</TD> <TD ALIGN=left NOWRAP><TABLE CELLSPACING=2 CELLPADDING=0> -<TR><TD ALIGN=left NOWRAP><TT>managers</TT></TD> +<TR><TD ALIGN=left NOWRAP><TT>management</TT></TD> </TR> -<TR><TD ALIGN=left NOWRAP><TT>workgroup1</TT></TD> +<TR><TD ALIGN=left NOWRAP><TT>marketing</TT></TD> </TR> -<TR><TD ALIGN=left NOWRAP><TT>workgroup2</TT></TD> +<TR><TD ALIGN=left NOWRAP><TT>sales</TT></TD> </TR></TABLE> </TD> <TD ALIGN=left NOWRAP><TABLE CELLSPACING=2 CELLPADDING=0> -<TR><TD ALIGN=left NOWRAP><TT>managers</TT></TD> +<TR><TD ALIGN=left NOWRAP><TT>management</TT></TD> </TR> -<TR><TD ALIGN=left NOWRAP><TT>workgroup1</TT></TD> +<TR><TD ALIGN=left NOWRAP><TT>marketing</TT></TD> </TR></TABLE> </TD> <TD ALIGN=left NOWRAP><TABLE CELLSPACING=2 CELLPADDING=0> -<TR><TD ALIGN=left NOWRAP><TT>managers</TT></TD> +<TR><TD ALIGN=left NOWRAP><TT>management</TT></TD> </TR> -<TR><TD ALIGN=left NOWRAP><TT>workgroup2</TT></TD> +<TR><TD ALIGN=left NOWRAP><TT>sales</TT></TD> </TR></TABLE></TD> </TR></TABLE> - <BR> -<DIV ALIGN=center>Table 2: Shared group example N2</DIV><BR> - - <A NAME="tab:srge2"></A> -<DIV ALIGN=center><HR WIDTH="80%" SIZE=2></DIV></DIV></BLOCKQUOTE> +<DIV CLASS="center"><HR WIDTH="80%" SIZE=2></DIV></DIV></BLOCKQUOTE> +</UL> <!--TOC subsection <TT>mod_stats</TT>--> -<H3><A NAME="htoc50">A.17</A> <TT>mod_stats</TT></H3><!--SEC END --> +<H3 CLASS="subsection"><A NAME="htoc53">A.16</A> <TT>mod_stats</TT></H3><!--SEC END --> <A NAME="sec:modstats"></A> -This module adds support for <A HREF="http://www.jabber.org/jeps/jep-0039.html">JEP-0039</A> (Statistics Gathering).<BR> -<BR> + +This module adds support for Statistics Gathering (<A HREF="http://www.jabber.org/jeps/jep-0039.html">JEP-0039</A>). This protocol +allows you to retrieve next statistics from your <TT>ejabberd</TT> deployment: +<UL CLASS="itemize"><LI CLASS="li-itemize"> +Total number of registered users on the current virtual host (users/total). +<LI CLASS="li-itemize">Total number of registered users on all virtual hosts (users/all-hosts/total). +<LI CLASS="li-itemize">Total number of online users on the current virtual host (users/online). +<LI CLASS="li-itemize">Total number of online users on all virtual hosts (users/all-hosts/online). +</UL> Options: -<DL COMPACT=compact><DT> -<B><TT>iqdisc</TT></B><DD> <TT>http://jabber.org/protocol/stats</TT> IQ queries processing -discipline (see <A HREF="#sec:modiqdiscoption">A.1.1</A>). +<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description"> +<B><TT>iqdisc</TT></B><DD CLASS="dd-description"> This specifies +the processing discipline for Statistics Gathering (<TT>http://jabber.org/protocol/stats</TT>) IQ queries +(see section <A HREF="#sec:modiqdiscoption">A.1.1</A>). </DL> +As there are only a small amount of clients (for example +<A HREF="http://tkabber.jabber.ru/">Tkabber</A>) and software libraries with +support for this JEP, a few examples are given of the XML you need to send +in order to get the statistics. Here they are: +<UL CLASS="itemize"><LI CLASS="li-itemize"> +You can request the number of online users on the current virtual host + (<TT>example.org</TT>) by sending: + <PRE CLASS="verbatim"> +<iq to='example.org' type='get'> + <query xmlns='http://jabber.org/protocol/stats'> + <stat name='users/online'/> + </query> +</iq> +</PRE><LI CLASS="li-itemize">You can request the total number of registered users on all virtual hosts + by sending: + <PRE CLASS="verbatim"> +<iq to='example.org' type='get'> + <query xmlns='http://jabber.org/protocol/stats'> + <stat name='users/all-hosts/total'/> + </query> +</iq> +</PRE></UL> <!--TOC subsection <TT>mod_time</TT>--> -<H3><A NAME="htoc51">A.18</A> <TT>mod_time</TT></H3><!--SEC END --> +<H3 CLASS="subsection"><A NAME="htoc54">A.17</A> <TT>mod_time</TT></H3><!--SEC END --> <A NAME="sec:modtime"></A> -This module answers UTC time on <TT>jabber:iq:time</TT> queries.<BR> + +This module features support for Entity Time (<A HREF="http://www.jabber.org/jeps/jep-0090.html">JEP-0090</A>). By using this JEP, +you are able to discover the time at another entity's location.<BR> <BR> Options: -<DL COMPACT=compact><DT> -<B><TT>iqdisc</TT></B><DD> <TT>jabber:iq:time</TT> IQ queries processing -discipline (see <A HREF="#sec:modiqdiscoption">A.1.1</A>). +<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description"> +<B><TT>iqdisc</TT></B><DD CLASS="dd-description"> This specifies +the processing discipline for Entity Time (<TT>jabber:iq:time</TT>) IQ queries +(see section <A HREF="#sec:modiqdiscoption">A.1.1</A>). </DL> <!--TOC subsection <TT>mod_vcard</TT>--> -<H3><A NAME="htoc52">A.19</A> <TT>mod_vcard</TT></H3><!--SEC END --> +<H3 CLASS="subsection"><A NAME="htoc55">A.18</A> <TT>mod_vcard</TT></H3><!--SEC END --> <A NAME="sec:modvcard"></A> -This module implements simple Jabber User Directory (based on user vCards) -and answers server vCard on <TT>vcard-temp</TT> queries.<BR> + +This module allows end users to store and retrieve their vCard, and to retrieve +other users vCards, as defined in vcard-temp (<A HREF="http://www.jabber.org/jeps/jep-0054.html">JEP-0054</A>). The module also +implements an uncomplicated Jabber User Directory based on the vCards of +these users. Moreover, it enables the server to send its vCard when queried.<BR> <BR> Options: -<DL COMPACT=compact><DT> - - <B><TT>host</TT></B><DD> Defines hostname of the service - (see <A HREF="#sec:modhostoption">A.1.2</A>). - <DT><B><TT>hosts</TT></B><DD> Defines hostnames of the service - (see <A HREF="#sec:modhostsoption">A.1.3</A>). If neither <TT>host</TT> nor <TT>hosts</TT> - are not present, then prefix <TT>vjud.</TT> is added to all <TT>ejabberd</TT> hostnames. - -<DT><B><TT>iqdisc</TT></B><DD> <TT>vcard-temp</TT> IQ queries processing -discipline (see <A HREF="#sec:modiqdiscoption">A.1.1</A>). -<DT><B><TT>search</TT></B><DD> Specifies whether search is enabled (value is <TT>true</TT>, default) or -disabled (value is <TT>false</TT>) by the service. If <TT>search</TT> is set to <TT>false</TT>, -option <TT>host</TT> is ignored and service does not appear in Jabber Discovery items. -<DT><B><TT>matches</TT></B><DD> Limits the number of reported search results. If value is set to -<TT>infinity</TT> then all search results are reported. Default value is <TT>30</TT>. -<DT><B><TT>allow_return_all</TT></B><DD> Specifies whether search with empty input fields can -return all known users. Default is <TT>false</TT>. -<DT><B><TT>search_all_hosts</TT></B><DD> If set in <TT>true</TT> then search returns matched -items at all virtual hosts. Otherwise only current host items are returned. -Default is <TT>true</TT>. +<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description"> + + <B><TT>hosts</TT></B><DD CLASS="dd-description"> This option defines the hostnames of the + service (see section <A HREF="#sec:modhostsoption">A.1.2</A>). If neither <TT>hosts</TT> nor + the old <TT>host</TT> is present, the prefix “<TT>vjud.</TT>” is added to all + <TT>ejabberd</TT> hostnames. + +<DT CLASS="dt-description"><B><TT>iqdisc</TT></B><DD CLASS="dd-description"> This specifies +the processing discipline for <TT>vcard-temp</TT> IQ queries +(see section <A HREF="#sec:modiqdiscoption">A.1.1</A>). +<DT CLASS="dt-description"><B><TT>search</TT></B><DD CLASS="dd-description"> This option specifies whether the search + functionality is enabled (value: <TT>true</TT>) or disabled + (value: <TT>false</TT>). If disabled, the option <TT>hosts</TT> will be + ignored and the Jabber User Directory service will not appear in the + Service Discovery item list. The default value is <TT>true</TT>. +<DT CLASS="dt-description"><B><TT>matches</TT></B><DD CLASS="dd-description"> With this option, the number of reported + search results can be limited. If the option's value is set to <TT>infinity</TT>, + all search results are reported. The default value is <TT>30</TT>. +<DT CLASS="dt-description"><B><TT>allow_return_all</TT></B><DD CLASS="dd-description"> 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 + <TT>false</TT>. +<DT CLASS="dt-description"><B><TT>search_all_hosts</TT></B><DD CLASS="dd-description"> If this option is + set to <TT>true</TT>, search operations will apply to all virtual hosts. + Otherwise only the current host will be searched. The default value is + <TT>true</TT>. </DL> -Example: -<PRE> +Examples: +<UL CLASS="itemize"><LI CLASS="li-itemize"> +In this first situation, search results are limited to twenty items, + every user who added information to their vCard will be listed when people + do an empty search, and only users from the current host will be returned: + <PRE CLASS="verbatim"> {modules, [ ... {mod_vcard, [{search, true}, {matches, 20}, {allow_return_all, true}, - {search_all_hosts, false}]} + {search_all_hosts, false}]}, ... ]}. -</PRE> +</PRE><LI CLASS="li-itemize">The second situation differs in a way that search results are not limited, + and that all virtual hosts will be searched instead of only the current one: + <PRE CLASS="verbatim"> + {modules, + [ + ... + {mod_vcard, [{search, true}, + {matches, infinity}, + {allow_return_all, true}]}, + ... + ]}. +</PRE></UL> <!--TOC subsection <TT>mod_version</TT>--> -<H3><A NAME="htoc53">A.20</A> <TT>mod_version</TT></H3><!--SEC END --> +<H3 CLASS="subsection"><A NAME="htoc56">A.19</A> <TT>mod_version</TT></H3><!--SEC END --> <A NAME="sec:modversion"></A> -This module answers <TT>ejabberd</TT> version on <TT>jabber:iq:version</TT> queries.<BR> + +This module implements Software Version (<A HREF="http://www.jabber.org/jeps/jep-0092.html">JEP-0092</A>). Consequently, it +answers <TT>ejabberd</TT>'s version when queried.<BR> <BR> Options: -<DL COMPACT=compact><DT> -<B><TT>iqdisc</TT></B><DD> <TT>jabber:iq:version</TT> IQ queries processing -discipline (see <A HREF="#sec:modiqdiscoption">A.1.1</A>). +<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description"> +<B><TT>iqdisc</TT></B><DD CLASS="dd-description"> This specifies +the processing discipline for Software Version (<TT>jabber:iq:version</TT>) IQ queries +(see section <A HREF="#sec:modiqdiscoption">A.1.1</A>). </DL> -<!--TOC section I18n/L10n--> +<!--TOC section Internationalization and Localization--> -<H2><A NAME="htoc54">B</A> I18n/L10n</H2><!--SEC END --> +<H2 CLASS="section"><A NAME="htoc57">B</A> Internationalization and Localization</H2><!--SEC END --> <A NAME="sec:i18nl10n"></A> -All built-in modules support <TT>xml:lang</TT> attribute inside IQ queries. -E. g. on figure <A HREF="#fig:discorus">2</A> showed the reply on the following query: -<PRE> + +All built-in modules support the <TT>xml:lang</TT> attribute inside IQ queries. +Figure <A HREF="#fig:discorus">2</A>, for example, shows the reply to the following query: +<PRE CLASS="verbatim"> <iq id='5' to='example.org' type='get' @@ -1451,35 +2121,325 @@ E. g. on figure <A HREF="#fig:discorus">2</A> showed the reply on the <query xmlns='http://jabber.org/protocol/disco#items'/> </iq> </PRE> -<BLOCKQUOTE><DIV ALIGN=center><DIV ALIGN=center><HR WIDTH="80%" SIZE=2></DIV> +<BLOCKQUOTE CLASS="figure"><DIV CLASS="center"><DIV CLASS="center"><HR WIDTH="80%" SIZE=2></DIV> <IMG SRC="discorus.png"> <BR> -<DIV ALIGN=center>Figure 2: Discovery result when <TT>xml:lang='ru'</TT></DIV><BR> +<BR> +<DIV CLASS="center">Figure 2: Service Discovery when <TT>xml:lang='ru'</TT></DIV><BR> +<BR> <A NAME="fig:discorus"></A> -<DIV ALIGN=center><HR WIDTH="80%" SIZE=2></DIV></DIV></BLOCKQUOTE> -Also web-interface supports <CODE>Accept-Language</CODE> HTTP header (see -figure <A HREF="#fig:webadmmainru">3</A>, compare it with figure <A HREF="#fig:webadmmain">1</A>) -<BLOCKQUOTE><DIV ALIGN=center><DIV ALIGN=center><HR WIDTH="80%" SIZE=2></DIV> +<DIV CLASS="center"><HR WIDTH="80%" SIZE=2></DIV></DIV></BLOCKQUOTE> +The web interface also supports the <CODE>Accept-Language</CODE> HTTP header (compare +figure <A HREF="#fig:webadmmainru">3</A> with figure <A HREF="#fig:webadmmain">1</A>) +<BLOCKQUOTE CLASS="figure"><DIV CLASS="center"><DIV CLASS="center"><HR WIDTH="80%" SIZE=2></DIV> <IMG SRC="webadmmainru.png"> <BR> -<DIV ALIGN=center>Figure 3: Web-administration top page with HTTP header - ``<CODE>Accept-Language: ru</CODE>''</DIV><BR> +<BR> +<DIV CLASS="center">Figure 3: Top page from the web interface with HTTP header + “Accept-Language: ru”</DIV><BR> +<BR> <A NAME="fig:webadmmainru"></A> -<DIV ALIGN=center><HR WIDTH="80%" SIZE=2></DIV></DIV></BLOCKQUOTE> +<DIV CLASS="center"><HR WIDTH="80%" SIZE=2></DIV></DIV></BLOCKQUOTE> +<!--TOC section Release Notes--> + +<H2 CLASS="section"><A NAME="htoc58">C</A> Release Notes</H2><!--SEC END --> + +<A NAME="sec:releasenotes"></A> + +<!--TOC subsection ejabberd 0.9--> + +<H3 CLASS="subsection"><A NAME="htoc59">C.1</A> ejabberd 0.9</H3><!--SEC END --> + +<PRE CLASS="verbatim"> + Release notes + ejabberd 0.9 + + This document describes the major new features of and changes to + ejabberd 0.9, compared to latest public release ejabber 0.7.5. + + For more detailed information, please refer to ejabberd User + Guide. + + +Virtual Hosting + + ejabberd now can host several domain on the same instance. + This option is enabled by using: + + {hosts, ["erlang-projects.org", "erlang-fr.org"]}. + + instead of the previous host directive. + + Note that you are now using a list of hosts. The main one should + be the first listed. See migration section further in this release + note for details. + + +Shared Roster + + Shared roster is a new feature that allow the ejabberd + administrator to add jabber user that will be present in the + roster of every users on the server. + Shared roster are enabled by adding: + + {mod_shared_roster, []} + + at the end of your module list in your ejabberd.cfg file. + + +PostgreSQL (ODBC) support + + This feature is experimental and not yet properly documented. This + feature is released for testing purpose. + + You need to have Erlang/OTP R10 to compile with ODBC on various + flavour of *nix. You should use Erlang/OTP R10B-4, as this task + has became easier with this release. It comes already build in + Erlang/OTP Microsoft Windows binary. + + PostgreSQL support is enabled by using the following module in + ejabberd.cfg instead of their standard counterpart: + + mod_last_odbc.erl + mod_offline_odbc.erl + mod_roster_odbc.erl + + The database schema is located in the src/odbc/pq.sql file. + + Look at the src/ejabberd.cfg.example file for more information on + how to configure ejabberd with odbc support. You can get support + on how to configure ejabberd with a relational database. + + +Migration from ejabberd 0.7.5 + + Migration is pretty straightforward as Mnesia database schema + conversions is handled automatically. Remember however that you + must backup your ejabberd database before migration. + + Here are the following steps to proceed: + + 1. Stop your instance of ejabberd. + + 2. In ejabberd.cfg, define the host lists. Change the host + directive to the hosts one: + Before: + {host, "erlang-projects.org"}. + After: + {hosts, ["erlang-projects.org", "erlang-fr.org"]}. + Note that when you restart the server the existing users will be + affected to the first virtual host, so the order is important. You + should keep the previous hostname as the first virtual host. + + 3. Restart ejabberd. + + +Bugfixes + + This release contains several bugfixes and architectural changes. + Please refer to the Changelog file supplied with this release for + details of all improvements in the ejabberd code. +</PRE> +<!--TOC subsection ejabberd 0.9.1--> + +<H3 CLASS="subsection"><A NAME="htoc60">C.2</A> ejabberd 0.9.1</H3><!--SEC END --> + +<PRE CLASS="verbatim"> + Release notes + ejabberd 0.9.1 + + This document describes the main changes from [25]ejabberd 0.9. + + The code can be downloaded from the [26]download page. + + For more detailed information, please refer to ejabberd [27]User Guide. + + +Groupchat (Multi-user chat and IRC) improvements + + The multi-user chat code has been improved to comply with the latest version + of Jabber Enhancement Proposal 0045. + + The IRC (Internet Relay Chat) features now support WHOIS and USERINFO + requests. + + +Web interface + + ejabberd modules management features have been added to the web interface. + They now allow to start or stop extension module without restarting the + ejabberd server. + + +Publish and subscribe + + It is now possible to a subscribe node with a JabberID that includes a + resource. + + +Translations + + A new script has been included to help translate ejabberd into new languages + and maintain existing translations. + + As a result, ejabberd is now translating into 10 languages: + * Dutch + * English + * French + * German + * Polish + * Portuguese + * Russian + * Spanish + * Swedish + * Ukrainian + + +Migration + + No changes have been made to the database. No particular conversion steps + are needed. However, you should backup your database before upgrading to a + new ejabberd version. + + +Bugfixes + + This release contains several bugfixes and architectural changes. Please + refer to the Changelog file supplied with this release for details of all + improvements in the ejabberd code. +</PRE> +<!--TOC subsection ejabberd 0.9.8--> + +<H3 CLASS="subsection"><A NAME="htoc61">C.3</A> ejabberd 0.9.8</H3><!--SEC END --> + +<PRE CLASS="verbatim"> + Release notes + ejabberd 0.9.8 + 2005-08-01 + + This document describes the main changes in ejabberd 0.9.8. This + version prepares the way for the release of ejabberd 1.0, which + is due later this year. + + The code can be downloaded from the Process-one website: + http://www.process-one.net/en/projects/ejabberd/ + + For more detailed information, please refer to ejabberd User Guide + on the Process-one website: + http://www.process-one.net/en/projects/ejabberd/docs.html + + + Recent changes include.... + + +Enhanced virtual hosting + + Virtual hosting applies to many more setting options and + features and is transparent. Virtual hosting accepts different + parameters for different virtual hosts regarding the following + features: authentication method, access control lists and access + rules, users management, statistics, and shared roster. The web + interface gives access to each virtual host's parameters. + + +Enhanced Publish-Subscribe module + + ejabberd's Publish-Subscribe module integrates enhancements + coming from J-EAI, an XMPP-based integration server built on + ejabberd. ejabberd thus supports Publish-Subscribe node + configuration. It is possible to define nodes that should be + persistent, and the number of items to persist. Besides that, it + is also possible to define various notification parameters, such + as the delivery of the payload with the notifications, and the + notification of subscribers when some changes occur on items. + Other examples are: the maximum size of the items payload, the + subscription approvers, the limitation of the notification to + online users only, etc. + + +Code reorganisation and update + + - The mod_register module has been cleaned up. + - ODBC support has been updated and several bugs have been fixed. + + +Development API + + To ease the work of Jabber/XMPP developers, a filter_packet hook + has been added. As a result it is possible to develop plugins to + filter or modify packets flowing through ejabberd. + + +Translations + + - Translations have been updated to support the new Publish-Subscribe features. + - A new Brazilian Portuguese translation has been contributed. + + +Web interface + + - The CSS stylesheet from the web interface is W3C compliant. + + +Installers + + Installers are provided for Microsoft Windows and Linux/x86. The + Linux installer includes Erlang ASN.1 modules for LDAP + authentication support. + + +Bugfixes + + - This release contains several bugfixes and architectural + changes. Among other bugfixes include improvements in LDAP + authentication. Please refer to the ChangeLog file supplied + with this release regarding all improvements in ejabberd. + + +References + + The ejabberd feature sheet helps comparing with other Jabber/XMPP + servers: + http://www.process-one.net/en/projects/ejabberd/docs/features.pdf + + Contributed tutorials of interest are: + - Migration from Jabberd1.4 to ejabberd: + http://ejabberd.jabber.ru/jabberd1-to-ejabberd + - Migration from Jabberd2 to ejabberd: + http://ejabberd.jabber.ru/jabberd2-to-ejabberd + - Transport configuration for connecting to other networks: + http://ejabberd.jabber.ru/tutorials-transports + +END + +</PRE> +<!--TOC section Acknowledgements--> + +<H2 CLASS="section"><A NAME="htoc62">D</A> Acknowledgements</H2><!--SEC END --> + +<A NAME="sec:acknowledgements"></A> + +Thanks to all people who contributed to this guide: +<UL CLASS="itemize"><LI CLASS="li-itemize"> +Alexey Shchepin (<A HREF="xmpp:aleksey@jabber.ru"><TT>xmpp:aleksey@jabber.ru</TT></A>) +<LI CLASS="li-itemize">Florian Zumbiehl (<A HREF="xmpp:florz@florz.de"><TT>xmpp:florz@florz.de</TT></A>) +<LI CLASS="li-itemize">Michael Grigutsch (<A HREF="xmpp:migri@jabber.i-pobox.net"><TT>xmpp:migri@jabber.i-pobox.net</TT></A>) +<LI CLASS="li-itemize">Mickaël Rémond (<A HREF="xmpp:mremond@erlang-projects.org"><TT>xmpp:mremond@erlang-projects.org</TT></A>) +<LI CLASS="li-itemize">Sander Devrieze (<A HREF="xmpp:sander@devrieze.dyndns.org"><TT>xmpp:sander@devrieze.dyndns.org</TT></A>) +<LI CLASS="li-itemize">Sergei Golovan (<A HREF="xmpp:sgolovan@nes.ru"><TT>xmpp:sgolovan@nes.ru</TT></A>) +<LI CLASS="li-itemize">Vsevolod Pelipas (<A HREF="xmpp:vsevoload@jabber.ru"><TT>xmpp:vsevoload@jabber.ru</TT></A>) +</UL> <!--HTMLFOOT--> <!--ENDHTML--> <!--FOOTER--> -<HR SIZE=2> -<BLOCKQUOTE><EM>This document was translated from L<sup>A</sup>T<sub>E</sub>X by -</EM><A HREF="http://pauillac.inria.fr/~maranget/hevea/index.html"><EM>H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A</EM></A><EM>. -</EM></BLOCKQUOTE> -</BODY> +<HR SIZE=2><BLOCKQUOTE CLASS="quote"><EM>This document was translated from L<sup>A</sup>T<sub>E</sub>X by +</EM><A HREF="http://pauillac.inria.fr/~maranget/hevea/index.html"><EM>H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A</EM></A><EM>.</EM></BLOCKQUOTE></BODY> </HTML> diff --git a/doc/guide.tex b/doc/guide.tex index de5f8ede0..61965b82d 100644 --- a/doc/guide.tex +++ b/doc/guide.tex @@ -1,19 +1,27 @@ \documentclass[a4paper,10pt]{article} +%% Packages +\usepackage{float} \usepackage{graphics} \usepackage{hevea} +\usepackage[pdftex,colorlinks,unicode,urlcolor=blue,linkcolor=blue, + pdftitle=Ejabberd\ Installation\ and\ Operation\ Guide,pdfauthor=Alexey\ + Shchepin,pdfsubject=ejabberd,pdfkeywords=ejabberd, + pdfpagelabels=false]{hyperref} +\usepackage{makeidx} +%\usepackage{showidx} % Only for verifying the index entries. \usepackage{verbatim} +\usepackage{geometry} -\usepackage[twosideshift=0pt]{geometry} - -\usepackage[pdftex,colorlinks,unicode,urlcolor=blue,linkcolor=blue,pdftitle=Ejabberd\ - Installation\ and\ Operation\ Guide,pdfauthor=Alexey\ - Shchepin,pdfsubject=ejabberd,pdfkeywords=ejabberd]{hyperref} +%% Index +\makeindex +% Remove the index anchors from the HTML version to save size and bandwith. +\newcommand{\ind}[1]{\begin{latexonly}\index{#1}\end{latexonly}} +%% Images \newcommand{\logoscale}{0.7} \newcommand{\imgscale}{0.58} \newcommand{\insimg}[1]{\insscaleimg{\imgscale}{#1}} - \newcommand{\insscaleimg}[2]{ \imgsrc{#2}{} \begin{latexonly} @@ -21,8 +29,9 @@ \end{latexonly} } +%% Various \newcommand{\bracehack}{\def\{{\char"7B}\def\}{\char"7D}} - +\newcommand{\titem}[1]{\item[\bracehack\texttt{#1}]} \newcommand{\ns}[1]{\texttt{#1}} \newcommand{\jid}[1]{\texttt{#1}} \newcommand{\option}[1]{\texttt{#1}} @@ -33,6 +42,7 @@ \newcommand{\ejabberd}{\texttt{ejabberd}} \newcommand{\Jabber}{Jabber} +%% Modules \newcommand{\module}[1]{\texttt{#1}} \newcommand{\modannounce}{\module{mod\_announce}} \newcommand{\modconfigure}{\module{mod\_configure}} @@ -54,140 +64,128 @@ \newcommand{\modvcard}{\module{mod\_vcard}} \newcommand{\modversion}{\module{mod\_version}} -\newcommand{\titem}[1]{\item[\bracehack\texttt{#1}]} +%% Common options +\newcommand{\iqdiscitem}[1]{\titem{iqdisc} \ind{options!iqdisc}This specifies +the processing discipline for #1 IQ queries +(see section~\ref{sec:modiqdiscoption}).} +\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 + \ejabberd{} hostnames. +} + +%% Title page +\include{version} +\title{Ejabberd \version\ Installation and Operation Guide} +\author{Alexey Shchepin \\ + \ahrefurl{mailto:alexey@sevcom.net} \\ + \ahrefurl{xmpp:aleksey@jabber.ru}} -%\setcounter{tocdepth}{3} +%% 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 + +%% Footnotes \begin{latexonly} \global\parskip=9pt plus 3pt minus 1pt \global\parindent=0pt - \gdef\ahrefurl#1{\href{#1}{\texttt{#1}}} \gdef\footahref#1#2{#2\footnote{\href{#1}{\texttt{#1}}}} \end{latexonly} - \newcommand{\tjepref}[2]{\footahref{http://www.jabber.org/jeps/jep-#1.html}{#2}} \newcommand{\jepref}[1]{\tjepref{#1}{JEP-#1}} -\newcommand{\iqdiscitem}[1]{\titem{iqdisc} #1 IQ queries processing -discipline (see~\ref{sec:modiqdiscoption}).} -\newcommand{\hostitem}[1]{ - \titem{host} Defines hostname of the service - (see~\ref{sec:modhostoption}). - \titem{hosts} Defines hostnames of the service - (see~\ref{sec:modhostsoption}). If neither \texttt{host} nor \texttt{hosts} - are not present, then prefix \jid{#1.} is added to all \ejabberd{} hostnames. -} - -\title{Ejabberd Installation and Operation Guide} -\author{Alexey Shchepin \\ - \ahrefurl{mailto:alexey@sevcom.net} \\ - \ahrefurl{xmpp:aleksey@jabber.ru}} -\date{July 31, 2005} - \begin{document} + +\label{sec:titlepage} \begin{titlepage} \maketitle{} - - {\centering - \insscaleimg{\logoscale}{logo.png} + + \begin{center} + {\insscaleimg{\logoscale}{logo.png} \par } -\end{titlepage} -%\newpage -\tableofcontents{} + \end{center} -\newpage -\section{Introduction} -\label{sec:intro} + \begin{quotation}\textit{I can thoroughly recommend ejabberd for ease of setup -- + Kevin Smith, Current maintainer of the Psi project}\end{quotation} -\ejabberd{} is a Free and Open Source fault-tolerant distributed \Jabber{} -server. It is written mostly in Erlang. +\end{titlepage} -The main features of \ejabberd{} are: -\begin{itemize} -\item Works on most of popular platforms: *nix (tested on Linux, FreeBSD and - NetBSD) and Win32 -\item Distributed: You can run \ejabberd{} on a cluster of machines to let all of - them serve one Jabber domain. -\item Fault-tolerance: You can setup an \ejabberd{} cluster so that all the - information required for a properly working service will be stored - permanently on more than one node. This means that if one of the nodes - crashes, then the others will continue working without disruption. - You can also add or replace nodes ``on the fly''. -\item Support for virtual hosting -\item Built-in \tjepref{0045}{Multi-User Chat} service -\item Built-in IRC transport -\item Built-in \tjepref{0060}{Publish-Subscribe} service -\item Built-in Jabber Users Directory service based on users vCards -\item Built-in web-based administration interface -\item Built-in \tjepref{0025}{HTTP Polling} service -\item SSL support -\item Support for LDAP authentication -\item Ability to interface with external components (JIT, MSN-t, Yahoo-t, etc.) -\item Migration from jabberd14 is possible -\item Mostly XMPP-compliant -\item Support for \tjepref{0030}{Service Discovery}. -\item Support for \tjepref{0039}{Statistics Gathering}. -\item Support for \ns{xml:lang} -\end{itemize} +% Set the page counter to 2 so that the titlepage and the second page do not +% have the same page number. This fixes the PDFLaTeX warning "destination with +% the same identifier". +\begin{latexonly} +\setcounter{page}{2} +\end{latexonly} -The misfeatures of \ejabberd{} are: -\begin{itemize} -\item No support for authentication and STARTTLS in S2S connections -\end{itemize} +\tableofcontents{} +% Input introduction.tex +\input{introduction} \section{Installation from Source} \label{sec:installation} +\ind{installation} \subsection{Installation Requirements} \label{sec:installreq} -\subsubsection{Unix} +\subsubsection{``Unix-like'' operating systems} \label{sec:installrequnix} +\ind{installation!requirements for ``Unix-like'' operating systems} -To compile \ejabberd{}, you will need the following packages: +To compile \ejabberd{} on a ``Unix-like'' operating system, you need: \begin{itemize} \item GNU Make; \item GCC; -\item libexpat 1.95 or later; -\item Erlang/OTP R8B or later; -\item OpenSSL 0.9.6 or later (optional). +\item libexpat 1.95 or higher; +\item Erlang/OTP R8B or higher; +\item OpenSSL 0.9.6 or higher (optional). \end{itemize} \subsubsection{Windows} \label{sec:installreqwin} +\ind{installation!requirements for Windows} -To compile \ejabberd{} in MS Windows environment, you will need the following -packages: +To compile \ejabberd{} on a Windows flavour, you need: \begin{itemize} \item MS Visual C++ 6.0 Compiler -\item \footahref{http://erlang.org/download/otp\_win32\_R10B-1a.exe}{Erlang/OTP R10B-1a} -\item \footahref{http://prdownloads.sourceforge.net/expat/expat\_win32bin\_1\_95\_7.exe?download}{Expat 1.95.7} +\item \footahref{http://erlang.org/download.html}{Erlang/OTP R8B or higher} +\item \footahref{http://sourceforge.net/project/showfiles.php?group\_id=10127\&package\_id=11277}{Expat 1.95.7 or higher} \item -\footahref{http://ftp.gnu.org/pub/gnu/libiconv/libiconv-1.9.1.tar.gz}{Iconv 1.9.1} +\footahref{http://www.gnu.org/software/libiconv/}{Iconv 1.9.1} (optional) \item \footahref{http://www.slproweb.com/products/Win32OpenSSL.html}{Shining Light OpenSSL} (to enable SSL connections) \end{itemize} - -\subsection{Obtaining} +\subsection{Obtaining \ejabberd{}} \label{sec:obtaining} -Stable \ejabberd{} release can be obtained at +\ind{download} +Released versions of \ejabberd{} can be obtained from \\ \ahrefurl{http://www.process-one.net/en/projects/ejabberd/download.html}. -The latest alpha version can be retrieved from Subversion repository\@. +\ind{Subversion repository} +The latest development version can be retrieved from the Subversion repository\@. \begin{verbatim} - svn co svn://svn.process-one.net/opt/data/svn/ejabberd/trunk ejabberd + svn co http://svn.process-one.net/ejabberd/trunk ejabberd \end{verbatim} - \subsection{Compilation} \label{sec:compilation} -\subsubsection{Unix} +\ind{compilation} + +\subsubsection{``Unix-like'' operating systems} \label{sec:compilationunix} +\ind{compilation!on ``Unix-like'' operating systems} + +Compile \ejabberd{} on a ``Unix-like'' operating system by executing: \begin{verbatim} ./configure @@ -196,50 +194,53 @@ The latest alpha version can be retrieved from Subversion repository\@. make install \end{verbatim} -This will install \ejabberd{} to \verb|/var/lib/ejabberd| directory, -\verb|ejabberd.cfg| to \verb|/etc/ejabberd| directory and create -\verb|/var/log/ejabberd| directory for log files. +These commands will: +\begin{itemize} +\item install \ejabberd{} into the directory \verb|/var/lib/ejabberd|, +\item install the configuration file into \verb|/etc/ejabberd|, +\item create a directory called \verb|/var/log/ejabberd| to store log files. +\end{itemize} \subsubsection{Windows} \label{sec:compilationwin} +\ind{compilation!on Windows} \begin{itemize} \item Install Erlang emulator (for example, into \verb|C:\Program Files\erl5.3|). \item Install Expat library into \verb|C:\Program Files\Expat-1.95.7| directory. - + Copy file \verb|C:\Program Files\Expat-1.95.7\Libs\libexpat.dll| to your Windows system directory (for example, \verb|C:\WINNT| or \verb|C:\WINNT\System32|) -\item Build and install Iconv library into \verb|C:\Program Files\iconv-1.9.1| directory. - +\item Build and install the Iconv library into the directory + \verb|C:\Program Files\iconv-1.9.1|. + Copy file \verb|C:\Program Files\iconv-1.9.1\bin\iconv.dll| to your - Windows system directory. - - Note: Instead of copying libexpat.dll and iconv.dll to Windows - directory, you can add directories + Windows system directory (more installation instructions can be found in the + file README.woe32 in the iconv distribution). + + Note: instead of copying libexpat.dll and iconv.dll to the Windows + directory, you can add the directories \verb|C:\Program Files\Expat-1.95.7\Libs| and - \verb|C:\Program Files\iconv-1.9.1\bin| to \verb|PATH| environment + \verb|C:\Program Files\iconv-1.9.1\bin| to the \verb|PATH| environment variable. -\item Being in \verb|ejabberd\src| directory run: +\item While in the directory \verb|ejabberd\src| run: \begin{verbatim} configure.bat nmake -f Makefile.win32 \end{verbatim} -\item Edit file \verb|ejabberd\src\ejabberd.cfg| and run +\item Edit the file \verb|ejabberd\src\ejabberd.cfg| and run \begin{verbatim} werl -s ejabberd -name ejabberd \end{verbatim} \end{itemize} -%\subsection{Initial Configuration} -%\label{sec:initconfig} - - \subsection{Starting} \label{sec:starting} +\ind{starting} -To start \ejabberd{}, use the following command: +Execute the following command to start \ejabberd{}: \begin{verbatim} erl -pa /var/lib/ejabberd/ebin -name ejabberd -s ejabberd \end{verbatim} @@ -247,15 +248,16 @@ or \begin{verbatim} erl -pa /var/lib/ejabberd/ebin -sname ejabberd -s ejabberd \end{verbatim} -In the latter case Erlang node will be identified using only first part of host -name, i.\,e. other Erlang nodes outside this domain can't contact this node. +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 +this node. -Note that when using above command \ejabberd{} will search for config file -in current directory and will use current directory for storing user database -and logging. +Note that when using the above command, \ejabberd{} will search for the +configuration file in the current directory and will use the current directory +for storing its user database and for logging. -To specify path to config file, log files and Mnesia database directory, -you may use the following command: +To specify the path to the configuration file, the log files and the Mnesia +database directory, you may use the following command: \begin{verbatim} erl -pa /var/lib/ejabberd/ebin \ -sname ejabberd \ @@ -266,17 +268,18 @@ you may use the following command: -mnesia dir \"/var/lib/ejabberd/spool\" \end{verbatim} -You can find other useful options in Erlang manual page (\shell{erl -man erl}). +You can find other useful options in the Erlang manual page +(\shell{erl -man erl}). -To use more than 1024 connections, you should set environment variable +To use more than 1024 connections, you should set the environment variable \verb|ERL_MAX_PORTS|: \begin{verbatim} export ERL_MAX_PORTS=32000 \end{verbatim} -Note that with this value \ejabberd{} will use more memory (approximately 6MB +Note that with this value, \ejabberd{} will use more memory (approximately 6\,MB more). -To reduce memory usage, you may set environment variable +To reduce memory usage, you may set the environment variable \verb|ERL_FULLSWEEP_AFTER|: \begin{verbatim} export ERL_FULLSWEEP_AFTER=0 @@ -289,138 +292,153 @@ But in this case \ejabberd{} can start to work slower. \subsection{Initial Configuration} \label{sec:initconfig} +\ind{configuration file} -The configuration file is initially loaded the first time \ejabberd{} is -executed, when it is parsed and stored in a database. Subsequently the -configuration is loaded from the database and any commands in the configuration -file are appended to the entries in the database. The configuration file -consists of a sequence of Erlang terms. Parts of lines after \term{`\%'} sign -are ignored. Each term is tuple, where first element is name of option, and -other are option values. E.\,g.\ if this file does not contain a ``host'' -definition, then old value stored in the database will be used. +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 +configuration will be loaded from the database and any commands in the +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 +host name(s) stored in the database will be used. -To override old values stored in the database the following lines can be added -in config: +You can override the old values stored in the database by adding next lines to +the configuration file: \begin{verbatim} override_global. override_local. override_acls. \end{verbatim} -With this lines old global or local options or ACLs will be removed before -adding new ones. - +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} +\ind{options!hosts}\ind{host names} -Option \option{hosts} defines a list of \Jabber{} domains that \ejabberd{} -serves. E.\,g.\ to serve \jid{example.org} and \jid{example.com} domains add -the following line in the config: -\begin{verbatim} - {hosts, ["example.org", "example.com"]}. -\end{verbatim} +The option \option{hosts} defines a list containing one or more domains that +\ejabberd{} will serve. -Option \option{host} defines one \Jabber{} domain that \ejabberd{} serves. -E.\,g.\ to serve only \jid{example.org} domain add the following line in the -config: -\begin{verbatim} +Examples: +\begin{itemize} +\item Serving one domain: +\begin{itemize} +\item \begin{verbatim} + {hosts, ["example.org"]}. +\end{verbatim} +\item Backwards compatibility with older \ejabberd{} versions can be retained + with: + \begin{verbatim} {host, "example.org"}. \end{verbatim} -It have the same effect as +\end{itemize} +\item Serving two domains: \begin{verbatim} - {hosts, ["example.org"]}. + {hosts, ["one.org", "two.org"]}. \end{verbatim} - -%This option is mandatory. +\end{itemize} \subsubsection{Default Language} \label{sec:configlanguage} +\ind{options!language}\ind{language} + +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{<language>.msg} in \ejabberd{}'s \term{msgs} directory. -Option \option{language} defines default language of \ejabberd{} messages, sent -to users. Default value is \term{"en"}. In order to take effect there must be a -translation file \term{<language>.msg} in \ejabberd{} \term{msgs} directory. -E.\,g.\ to use Russian as default language add the following line in the config: +Examples: +\begin{itemize} +\item To set Russian as default language: \begin{verbatim} {language, "ru"}. \end{verbatim} - +\item To set Spanish as default language: +\begin{verbatim} + {language, "es"}. +\end{verbatim} +\end{itemize} \subsubsection{Access Rules} \label{sec:configaccess} +\ind{options!acl}\ind{access rules}\ind{ACL}\ind{Access Control List} -Access control in \ejabberd{} is performed via Access Control Lists (ACL). The -declarations of ACL in config file have following syntax: +Access control in \ejabberd{} is performed via Access Control Lists (ACLs). The +declarations of ACLs in the configuration file have the following syntax: \begin{verbatim} {acl, <aclname>, {<acltype>, ...}}. \end{verbatim} -\term{<acltype>} can be one of following: +\term{<acltype>} can be one of the following: \begin{description} -\titem{all} Matches all JIDs. Example: +\titem{all} Matches all JIDs. Example: \begin{verbatim} {acl, all, all}. \end{verbatim} -\titem{\{user, <username>\}} Matches user with name - \term{<username>} at the first virtual host. Example: +\titem{\{user, <username>\}} Matches the user with the name + \term{<username>} at the first virtual host. Example: \begin{verbatim} -{acl, admin, {user, "aleksey"}}. +{acl, admin, {user, "yozhik"}}. \end{verbatim} -\titem{\{user, <username>, <server>\}} Matches user with JID - \term{<username>@<server>} and any resource. Example: +\titem{\{user, <username>, <server>\}} Matches the user with the JID + \term{<username>@<server>} and any resource. Example: \begin{verbatim} -{acl, admin, {user, "aleksey", "jabber.ru"}}. +{acl, admin, {user, "yozhik", "example.org"}}. \end{verbatim} \titem{\{server, <server>\}} Matches any JID from server - \term{<server>}. Example: + \term{<server>}. Example: \begin{verbatim} -{acl, jabberorg, {server, "jabber.org"}}. +{acl, exampleorg, {server, "example.org"}}. \end{verbatim} -\titem{\{user\_regexp, <regexp>\}} Matches local user with name that - matches \term{<regexp>} at the first virtual host. Example: +\titem{\{user\_regexp, <regexp>\}} Matches any local user with a name that + matches \term{<regexp>} at the first virtual host. Example: \begin{verbatim} {acl, tests, {user, "^test[0-9]*$"}}. \end{verbatim} %$ -\titem{\{user\_regexp, <regexp>, <server>\}} Matches user with name - that matches \term{<regexp>} and from server \term{<server>}. Example: +\titem{\{user\_regexp, <regexp>, <server>\}} Matches any user with a name + that matches \term{<regexp>} at server \term{<server>}. Example: \begin{verbatim} {acl, tests, {user, "^test", "example.org"}}. \end{verbatim} -\titem{\{server\_regexp, <regexp>\}} Matches any JID from server that - matches \term{<regexp>}. Example: +\titem{\{server\_regexp, <regexp>\}} Matches any JID from the server that + matches \term{<regexp>}. Example: \begin{verbatim} {acl, icq, {server, "^icq\\."}}. \end{verbatim} -\titem{\{node\_regexp, <user\_regexp>, <server\_regexp>\}} Matches user - with name that matches \term{<user\_regexp>} and from server that matches - \term{<server\_regexp>}. Example: +\titem{\{node\_regexp, <user\_regexp>, <server\_regexp>\}} Matches any user + with a name that matches \term{<user\_regexp>} at any server that matches + \term{<server\_regexp>}. Example: \begin{verbatim} -{acl, aleksey, {node_regexp, "^aleksey$", "^jabber.(ru|org)$"}}. +{acl, yohzik, {node_regexp, "^yohzik$", "^example.(com|org)$"}}. \end{verbatim} \titem{\{user\_glob, <glob>\}} \titem{\{user\_glob, <glob>, <server>\}} \titem{\{server\_glob, <glob>\}} -\titem{\{node\_glob, <user\_glob>, <server\_glob>\}} This is same as - above, but uses shell glob patterns instead of regexp. These patterns can - have following special characters: +\titem{\{node\_glob, <user\_glob>, <server\_glob>\}} This is the same as + above. However, it uses shell glob patterns instead of regexp. These patterns + can have the following special characters: \begin{description} \titem{*} matches any string including the null string. \titem{?} matches any single character. - \titem{[...]} matches any of the enclosed characters. Character + \titem{[...]} matches any of the enclosed characters. Character ranges are specified by a pair of characters separated by a \term{`-'}. - If the first character after \term{`['} is a \term{`!'}, then any + If the first character after \term{`['} is a \term{`!'}, any character not enclosed is matched. \end{description} \end{description} The following ACLs are pre-defined: \begin{description} -\titem{all} Matches all JIDs. -\titem{none} Matches none JIDs. +\titem{all} Matches any JID. +\titem{none} Matches no JID. \end{description} -An entry allowing or denying access to different services would look similar to +An entry allowing or denying access to different services looks similar to this: \begin{verbatim} {access, <accessname>, [{allow, <aclname>}, @@ -429,9 +447,9 @@ this: ]}. \end{verbatim} When a JID is checked to have access to \term{<accessname>}, the server -sequentially checks if this JID mathes one of the ACLs that are second elements -in each tuple in list. If it is matched, then the first element of matched -tuple is returned else ``\term{deny}'' is returned. +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 ``\term{deny}'' is returned. Example: \begin{verbatim} @@ -440,118 +458,161 @@ Example: {allow, all}]}. \end{verbatim} -Following access rules pre-defined: +The following access rules are pre-defined: \begin{description} \titem{all} Always returns ``\term{allow}'' \titem{none} Always returns ``\term{deny}'' \end{description} - -\subsubsection{Shapers Configuration} +\subsubsection{Shapers} \label{sec:configshaper} +\ind{options!shaper}\ind{options!maxrate}\ind{shapers}\ind{maxrate}\ind{traffic speed} -With shapers is possible to bound connection traffic. The declarations of -shapers in config file have following syntax: +Shapers enable you to limit connection traffic. The syntax of +shapers is like this: \begin{verbatim} {shaper, <shapername>, <kind>}. \end{verbatim} -Currently implemented only one kind of shaper: \term{maxrate}. It have +Currently only one kind of shaper called \term{maxrate} is available. It has the following syntax: \begin{verbatim} {maxrate, <rate>} \end{verbatim} -where \term{<rate>} means maximum allowed incomig rate in bytes/second. -E.\,g.\ to define shaper with name ``\term{normal}'' and maximum allowed rate -1000\,bytes/s, add following line in config: +where \term{<rate>} stands for the maximum allowed incomig rate in bytes per +second. + +Examples: +\begin{itemize} +\item To define a shaper named ``\term{normal}'' with traffic speed limited to +1,000\,bytes/second: \begin{verbatim} {shaper, normal, {maxrate, 1000}}. \end{verbatim} - +\item To define a shaper named ``\term{fast}'' with traffic speed limited to +50,000\,bytes/second: +\begin{verbatim} + {shaper, fast, {maxrate, 50000}}. +\end{verbatim} +\end{itemize} \subsubsection{Listened Sockets} \label{sec:configlistened} +\ind{options!listen} -Option \option{listen} defines list of listened sockets and what services -runned on them. Each element of list is a tuple with following elements: +The option \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: \begin{itemize} -\item Port number; -\item Module that serves this port; +\item Port number. +\item Module that serves this port. \item Options to this module. \end{itemize} -Currently these modules are implemented: -\begin{description} - \titem{ejabberd\_c2s} This module serves C2S connections. - - The following options are defined: - \begin{description} - \titem{\{access, <access rule>\}} This option defines access of users - to this C2S port. Default value is ``\term{all}''. - \titem{\{shaper, <access rule>\}} This option is like previous, but - use shapers instead of ``\term{allow}'' and ``\term{deny}''. Default - value is ``\term{none}''. - \titem{\{ip, IPAddress\}} This option specifies which network interface to - listen on. For example \verb|{ip, {192, 168, 1, 1}}|. - \titem{inet6} Set up the socket for IPv6. - \titem{starttls} This option specifies that STARTTLS extension is available - on connections to this port. You should also set ``\verb|certfile|'' - option. - \titem{tls} This option specifies that traffic on this port will be - encrypted using SSL immediately after connecting. You should also set - ``\verb|certfile|'' option. - \titem{ssl} This option specifies that traffic on this port will be - encrypted using SSL. You should also set ``\verb|certfile|'' option. It - is recommended to use \term{tls} option instead. - \titem{\{certfile, Path\}} Path to a file containing the SSL certificate. - \end{description} - \titem{ejabberd\_s2s\_in} This module serves incoming S2S connections. - \titem{ejabberd\_service} This module serves connections from \Jabber{} - services (i.\,e.\ that use the \ns{jabber:component:accept} namespace). - - The following additional options are defined for \term{ejabberd\_service} - (options \option{access}, \option{shaper}, \option{ip}, \option{inet6} are - still valid): - \begin{description} - \titem{\{host, Hostname, [HostOptions]\}} This option defines hostname of connected - service and allows to specify additional options, e.\,g.\ - \poption{\{password, Secret\}}. - \titem{\{hosts, [Hostnames], [HostOptions]\}} The same as above, but allows to - specify several hostnames. - \end{description} - \titem{ejabberd\_http} This module serves incoming HTTP connections. +\ind{modules!ejabberd\_c2s}\ind{modules!ejabberd\_s2s\_in}\ind{modules!ejabberd\_service}\ind{modules!ejabberd\_http}\ind{protocols!JEP-0114: Jabber Component Protocol} +Currently next modules are implemented: +\begin{table}[H] + \centering + \begin{tabular}{|l|l|l|l|l|} + \hline \texttt{ejabberd\_c2s}& Description& Handles c2s connections.\\ + \cline{2-3} & Options& \texttt{access}, \texttt{certfile}, \texttt{inet6}, + \texttt{ip}, \texttt{shaper}, \texttt{ssl}, \texttt{tls}, + \texttt{starttls},\\ + & &\texttt{starttls\_required}\\ + \hline \texttt{ejabberd\_s2s\_in}& Description& Handles incoming s2s + connections.\\ + \cline{2-3} & Options& \texttt{inet6}, \texttt{ip}\\ + \hline \texttt{ejabberd\_service}& Description& Interacts with external + components (*).\\ + \cline{2-3} & Options& \texttt{access}, \texttt{hosts}, \texttt{inet6}, + \texttt{ip}, \texttt{shaper}\\ + \hline \texttt{ejabberd\_http}& Description& Handles incoming HTTP + connections.\\ + \cline{2-3} & Options& \texttt{certfile}, \texttt{http\_poll}, + \texttt{inet6}, \texttt{ip}, \texttt{tls}, \texttt{web\_admin}\\ + \hline + \end{tabular} +\end{table} - The following options are defined: - \begin{description} - \titem{http\_poll} This option enables \jepref{0025} (HTTP Polling) - support. It is available then at \verb|http://server:port/http-poll/|. - - \titem{web\_admin} This option enables web-based interface for \ejabberd{} - administration which is available at \verb|http://server:port/admin/|, - login and password should be equal to username and password of one of - registered users who have permission defined in ``configure'' access rule. - \end{description} +(*) The mechanism for \footahref{http://ejabberd.jabber.ru/tutorials-transports}{external components} is defined in Jabber Component Protocol (\jepref{0114}). + +The following options are available: +\begin{description} + \titem{\{access, <access rule>\}} \ind{options!access}This option defines + access to the port. The default value is ``\term{all}''. + \titem{\{certfile, Path\}} Path to a file containing the SSL certificate. + \titem{\{hosts, [Hostnames], [HostOptions]\}} \ind{options!hosts}This option + defines one or more hostnames of connected services and enables you to + specify additional options including \poption{\{password, Secret\}}. + \titem{http\_poll} \ind{options!http\_poll}\ind{protocols!JEP-0025: HTTP Polling}\ind{JWChat}\ind{web-based Jabber client} + This option enables HTTP Polling (\jepref{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 + \verb|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 + \footahref{http://jwchat.sourceforge.net/}{JWChat} (there is a tutorial to + \footahref{http://ejabberd.jabber.ru/jwchat}{install JWChat} with + instructions for \ejabberd{}). + \titem{inet6} \ind{options!inet6}\ind{IPv6}Set up the socket for IPv6. + \titem{\{ip, IPAddress\}} \ind{options!ip}This option specifies which network + interface to listen for. For example \verb|{ip, {192, 168, 1, 1}}|. + \titem{\{shaper, <access rule>\}} \ind{options!shaper}This option defines a + shaper for the port (see section~\ref{sec:configshaper}). The default value + is ``\term{none}''. + \titem{ssl} \ind{options!ssl}\ind{SSL}This option specifies that traffic on + the port will be encrypted using SSL. You should also set the + \option{certfile} option. It is recommended to use the \term{tls} option + instead. + \titem{starttls} \ind{options!starttls}\ind{modules!STARTTLS}This option + specifies that STARTTLS encryption is available on connections to the port. + You should also set the \option{certfile} option. + \titem{starttls\_required} \ind{options!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 + \option{certfile} option. + \titem{tls} \ind{options!tls}\ind{TLS}This option specifies that traffic on + the port will be encrypted using SSL immediately after connecting. You + should also set the \option{certfile} option. + \titem{web\_admin} \ind{options!web\_admin}\ind{web interface}This option + enables the web interface for \ejabberd{} administration which is available + at \verb|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. \end{description} -For example, the following configuration defines that: +For instance, the following configuration defines that: \begin{itemize} -\item C2S connections are listened on port 5222 and 5223 (SSL) and denied for - user ``\term{bad}'' -\item S2S connections are listened on port 5269 -\item HTTP connections are listened on port 5280 and administration interface - and HTTP Polling support are enabled -\item All users except admins have traffic limit 1000\,B/s -\item AIM transport \jid{aim.example.org} is connected to port 5233 with - password ``\term{aimsecret}'' -\item JIT transports \jid{icq.example.org} and \jid{sms.example.org} are - connected to port 5234 with password ``\term{jitsecret}'' -\item MSN transport \jid{msn.example.org} is connected to port 5235 with - password ``\term{msnsecret}'' -\item Yahoo! transport \jid{yahoo.example.org} is connected to port 5236 with - password ``\term{yahoosecret}'' -\item Gadu-Gadu transport \jid{gg.example.org} is connected to port 5237 with - password ``\term{ggsecret}'' -\item ILE service \jid{ile.example.org} is connected to port 5238 with - password ``\term{ilesecret}'' +\item c2s connections are listened for on port 5222 and 5223 (SSL) and denied + for the user ``\term{bad}'' +\item s2s connections are listened for on port 5269 +\item 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~\ref{sec:webadm} shows how exactly this can be done. +\item All users except for the administrators have a traffic of limit + 1,000\,Bytes/second +\item \ind{transports!AIM}The + \footahref{http://ejabberd.jabber.ru/pyaimt}{AIM transport} + \jid{aim.example.org} is connected to port 5233 with password + ``\term{aimsecret}'' +\item \ind{transports!ICQ}The ICQ transport JIT (\jid{icq.example.org} and + \jid{sms.example.org}) is connected to port 5234 with password + ``\term{jitsecret}'' +\item \ind{transports!MSN}The + \footahref{http://ejabberd.jabber.ru/pymsnt}{MSN transport} + \jid{msn.example.org} is connected to port 5235 with password + ``\term{msnsecret}'' +\item \ind{transports!Yahoo}The + \footahref{http://ejabberd.jabber.ru/yahoo-transport-2}{Yahoo! transport} + \jid{yahoo.example.org} is connected to port 5236 with password + ``\term{yahoosecret}'' +\item \ind{transports!Gadu-Gadu}The \footahref{http://ejabberd.jabber.ru/jabber-gg-transport}{Gadu-Gadu transport} \jid{gg.example.org} is + connected to port 5237 with password ``\term{ggsecret}'' +\item \ind{transports!email notifier}The + \footahref{http://ejabberd.jabber.ru/jmc}{Jabber Mail Component} + \jid{jmc.example.org} is connected to port 5238 with password + ``\term{jmcsecret}'' \end{itemize} \begin{verbatim} {acl, blocked, {user, "bad"}}. @@ -576,13 +637,13 @@ For example, the following configuration defines that: [{password, "yahoosecret"}]}]}, {5237, ejabberd_service, [{host, "gg.example.org", [{password, "ggsecret"}]}]}, - {5238, ejabberd_service, [{host, "ile.example.org", - [{password, "ilesecret"}]}]} + {5238, ejabberd_service, [{host, "jmc.example.org", + [{password, "jmcsecret"}]}]} ] }. \end{verbatim} -Note, that for jabberd14- or wpjabberd-based services you have to make the -transports log and do XDB by themselves: +Note, that for \ind{jabberd 1.4}jabberd 1.4- or \ind{WPJabber}WPJabber-based +services you have to make the transports log and do \ind{XDB}XDB by themselves: \begin{verbatim} <!-- You have to add elogger and rlogger entries here when using ejabberd. @@ -598,8 +659,8 @@ transports log and do XDB by themselves: <!-- Some Jabber server implementations do not provide - XDB services (for example jabberd 2.0 and ejabberd). - xdb_file_so is loaded in to handle all XDB requests. + XDB services (for example, jabberd2 and ejabberd). + xdb_file.so is loaded in to handle all XDB requests. --> <xdb id="xdb"> @@ -614,16 +675,17 @@ transports log and do XDB by themselves: </xdb> \end{verbatim} - \subsubsection{Modules} \label{sec:configmodules} +\ind{modules} -Option \term{modules} defines the list of modules that will be loaded after -\ejabberd{} startup. Each list element is a tuple where first element is a -name of a module and second is list of options to this module. See -section~\ref{sec:modules} for detailed information on each module. +The option \term{modules} defines the list of modules that will be loaded after +\ejabberd{} 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~\ref{sec:modules} for detailed information about each +module. -Example: +Example:\ind{modules!overview} \begin{verbatim} {modules, [{mod_register, []}, @@ -635,7 +697,7 @@ Example: {mod_vcard, []}, {mod_offline, []}, {mod_announce, [{access, announce}]}, - {mod_echo, [{host, "echo.example.org"}]}, + {mod_echo, [{hosts, ["echo.example.org"]}]}, {mod_private, []}, {mod_irc, []}, {mod_muc, []}, @@ -646,266 +708,415 @@ Example: ]}. \end{verbatim} - -\subsubsection{Virtual Host Configuration} +\subsubsection{Virtual Hosting} \label{sec:configvirtualhost} +\ind{virtual hosting}\ind{virtual hosts} -Options can be defined separately for different virtual hosts using -\term{host\_config} option. It have the have following syntax: +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, <hostname>, [<option>, <option>, ...]}. \end{verbatim} -Example: +Examples: +\begin{itemize} +\item Domain \jid{one.org} is using the internal authentication method while + domain \jid{two.org} is using the \ind{LDAP}LDAP server running on the domain + \jid{localhost} to perform authentication: \begin{verbatim} -{host_config, "example.org", [{auth_method, internal}]}. +{host_config, "one.org", [{auth_method, internal}]}. -{host_config, "example.com", [{auth_method, ldap}, +{host_config, "two.org", [{auth_method, ldap}, {ldap_servers, ["localhost"]}, {ldap_uidattr, "uid"}, {ldap_rootdn, "dc=localdomain"}, {ldap_rootdn, "dc=example,dc=com"}, {ldap_password, ""}]}. \end{verbatim} +\item Domain \jid{one.org} is using \ind{ODBC}ODBC to perform authentication + while domain \jid{two.org} is using the LDAP servers running on the domains + \jid{localhost} and \jid{otherhost}: +\begin{verbatim} +{host_config, "one.org", [{auth_method, odbc}, + {odbc_server, "DSN=ejabberd;UID=ejabberd;PWD=ejabberd"}]}. + +{host_config, "two.org", [{auth_method, ldap}, + {ldap_servers, ["localhost", "otherhost"]}, + {ldap_uidattr, "uid"}, + {ldap_rootdn, "dc=localdomain"}, + {ldap_rootdn, "dc=example,dc=com"}, + {ldap_password, ""}]}. +\end{verbatim} +\end{itemize} +\subsection{Creating an Initial Administrator} +\label{sec:initialadmin} +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: +\begin{enumerate} +\item Register an account on your \ejabberd{} deployment. An account can be + created in two ways: + \begin{enumerate} + \item Using the tool \term{ejabberdctl}\ind{ejabberdctl} (see + section~\ref{sec:ejabberdctl}): + \begin{verbatim} +% ejabberdctl node@host register admin example.org password +\end{verbatim} + \item Using In-Band Registration (see section~\ref{sec:modregister}): you can + use a \Jabber{} client to register an account. + \end{enumerate} +\item 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. + \begin{verbatim} + {acl, admins, {user, "admin", "example.org"}}. + {access, configure, [{allow, admins}]}. +\end{verbatim} +\item Restart \ejabberd{} to load the new configuration. +\item Open the web interface (\verb|http://server:port/admin/|) in your + favourite browser. Make sure to enter the \emph{full} JID as username (in this + example: \jid{admin@example.org}. The reason that you also need to enter the + suffix, is because \ejabberd{}'s virtual hosting support. +\end{enumerate} \subsection{Online Configuration and Monitoring} \label{sec:onlineconfig} -\subsubsection{Web-based Administration Interface} +\subsubsection{Web Interface} \label{sec:webadm} +\ind{web interface} -To perform online reconfiguration of \ejabberd{} you need to enable -\term{ejabberd\_http} listener with option \term{web\_admin} (see -section~\ref{sec:configlistened}). After that you can open URL -\verb|http://server:port/admin/| with you favorite web-browser and enter -username and password of an \ejabberd{} user with administrator rights. E.\,g. -with such config: -\begin{verbatim} +To perform online configuration of \ejabberd{} you need to enable the +\term{ejabberd\_http} listener with the option \term{web\_admin} (see +section~\ref{sec:configlistened}). Then you can open +\verb|http://server:port/admin/| in your favourite web browser. You +will be asked to enter the username (the \emph{full} \Jabber{} ID) and password +of an \ejabberd{} user with administrator rights. After authentication +you will see a page similar to figure~\ref{fig:webadmmain}. + +\begin{figure}[htbp] + \centering + \insimg{webadmmain.png} + \caption{Top page from the web interface} + \label{fig:webadmmain} +\end{figure} +Here you can edit access restrictions, manage users, create backups, +manage the database, enable/disable ports listened for, view server +statistics,\ldots + +Examples: +\begin{itemize} +\item You can serve the web interface on the same port as the + \ind{protocols!JEP-0025: HTTP Polling}HTTP Polling interface. In this example + you should point your web browser to \verb|http://example.org:5280/admin/| to + administer all virtual hosts or to + \verb|http://example.org:5280/admin/server/two.org/| to administer only the + virtual host \jid{two.org}. 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 + ``\jid{admin@one.org}'' to administer all virtual hosts (first URL). If you + log in with ``\jid{admin@two.org}'' on \\ + \verb|http://example.org:5280/admin/server/two.org/| you can only administer + the virtual host \jid{two.org}. + \begin{verbatim} ... - {host, "example.org"}. + {acl, admins, {user, "admin", "one.org"}}. + {host_config, "two.org", [{acl, admins, {user, "admin", "two.org"}}]}. + {access, configure, [{allow, admins}]}. + ... + {hosts, ["example.org"]}. ... {listen, [... - {5280, ejabberd_http, [web_admin]}, + {5280, ejabberd_http, [http_poll, web_admin]}, ... ] }. \end{verbatim} -you should enter URL \verb|http://example.org:5280/admin/|. After -authentication you should see something like in figure~\ref{fig:webadmmain}. -\begin{figure}[htbp] - \centering - \insimg{webadmmain.png} - \caption{Web-administration top page} - \label{fig:webadmmain} -\end{figure} -Here you can edit access restrictions, manage users, create backup files, -manage DB, enable/disable listened ports, and view statistics. - +\item 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 \verb|https://192.168.1.1:5280/admin/|: + \begin{verbatim} + ... + {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"}]}, + ... + ] + }. +\end{verbatim} +\end{itemize} -\subsubsection{\term{ejabberdctl} tool} +\subsubsection{\term{ejabberdctl}} \label{sec:ejabberdctl} -It is possible to do some administration operations using \term{ejabberdctl} -command-line tool. You can check available options running this command -without arguments: +It is possible to do some administration operations using the command +line tool \term{ejabberdctl}. You can list all available options by +running \term{ejabberdctl} without arguments: \begin{verbatim} % ejabberdctl Usage: ejabberdctl node command Available commands: + status get ejabberd status stop stop ejabberd restart restart ejabberd reopen-log reopen log file - register user password register a user - unregister user unregister a user - backup file store a database backup in file + 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 in a text 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 \end{verbatim} +Additional information: +\begin{description} +\titem{reopen-log } If you use a tool to rotate logs, you have to configure it + so that this command is executed after each rotation. +\titem {backup, restore, install-fallback, dump, load} You can use these + commands to create and restore backups. +%%More information about backuping can +%% be found in section~\ref{sec:backup}. +\titem{import-file, import-dir} \ind{migration!from jabberd 1.4}\ind{migration!from jabberd2} + These options can be used to migrate from other \Jabber{}/XMPP servers. There + exist tutorials to \footahref{http://ejabberd.jabber.ru/jabberd1-to-ejabberd}{migrate from jabberd 1.4} + and to \footahref{http://ejabberd.jabber.ru/jabberd2-to-ejabberd}{migrate from jabberd2}. +\titem{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. +\end{description} + + +\section{Firewall Settings} +\label{sec:firewall} +\ind{firewall}\ind{ports}\ind{SASL}\ind{TLS}\ind{clustering!ports} + +You need to take the following ports in mind when configuring your firewall: +\begin{table}[H] + \centering + \begin{tabular}{|l|l|} + \hline Port& Description\\ + \hline \hline 5222& SASL and unencrypted c2s connections.\\ + \hline 5223& Obsolete SSL c2s connections.\\ + \hline 5269& s2s connections.\\ + \hline 4369& Only for clustering (see~\ref{sec:clustering}).\\ + \hline port range& Only for clustring (see~\ref{sec:clustering}). This range + is configurable (see~\ref{sec:starting}).\\ + \hline + \end{tabular} +\end{table} + + +\section{SRV Records} +\label{sec:srv} +\ind{SRV Records}\ind{clustering!SRV Records} + +\begin{itemize} +\item General information: + \footahref{http://en.wikipedia.org/wiki/SRV\_record}{SRV record} +\item Practical information: + \footahref{http://jabberd.jabberstudio.org/2/docs/section05.html\#5\_7}{Setting DNS SRV Records} +\end{itemize} \section{Clustering} \label{sec:clustering} +\ind{clustering} - -\subsection{How it works} +\subsection{How it Works} \label{sec:howitworks} +\ind{clustering!how it works} -A \Jabber{} domain is served by one or more \ejabberd{} nodes. These nodes can -be runned on different machines that are connected via a network. They all +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 \term{\~{}ejabberd/.erlang.cookie} must be the same on all nodes). This is -needed because all nodes exchange information about connected users, S2S +needed because all nodes exchange information about connected users, s2s connections, registered services, etc\ldots -Each \ejabberd{} node have following modules: +Each \ejabberd{} node has the following modules: \begin{itemize} -\item router; -\item local router. -\item session manager; -\item S2S manager; +\item router, +\item local router, +\item session manager, +\item s2s manager. \end{itemize} - \subsubsection{Router} +\ind{clustering!router} -This module is the main router of \Jabber{} packets on each node. It -routes them based on their destinations domains. It uses a global -routing table. A domain of packet destination is searched in the -routing table, and if it is found, then the packet is routed to -appropriate process. If no, then it is sent to the S2S manager. - +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. \subsubsection{Local Router} +\ind{clustering!local router} This module routes packets which have a destination domain equal to -this server name. If destination JID has a non-empty user part, then -it is routed to the session manager, else it is processed depending on -its content. - +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. \subsubsection{Session Manager} +\ind{clustering!session manager} -This module routes packets to local users. It searches to what user -resource a packet must be sent via a presence table. Then packet is -either routed to appropriate C2S process, or stored in offline +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. +\subsubsection{s2s Manager} +\ind{clustering!s2s manager} -\subsubsection{S2S Manager} - -This module routes packets to other \Jabber{} servers. First, it -checks if an opened S2S connection from the domain of the packet -source to the domain of packet destination is existing. If it is -existing, then the S2S manager routes the packet to the process -serving this connection, else a new connection is opened. +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. - -\subsection{How to setup ejabberd cluster} +\subsection{Clustering Setup} \label{sec:cluster} +\ind{clustering!setup} -Suppose you already setuped ejabberd on one of machines (\term{first}), and -you need to setup another one to make \ejabberd{} cluster. Then do +Suppose you already configured \ejabberd{} on one machine named (\term{first}), +and you need to setup another one to make an \ejabberd{} cluster. Then do following steps: \begin{enumerate} \item Copy \verb|~ejabberd/.erlang.cookie| file from \term{first} to \term{second}. - + (alt) You can also add ``\verb|-cookie content_of_.erlang.cookie|'' option to all ``\shell{erl}'' commands below. - -\item On \term{second} run under `\term{ejabberd}' user in a directory - where ejabberd will work later the following command: + +\item On \term{second} run as the `\term{ejabberd}' user in the directory + where \ejabberd{} will work later the following command: \begin{verbatim} erl -sname ejabberd \ -mnesia extra_db_nodes "['ejabberd@first']" \ -s mnesia \end{verbatim} - - This will start mnesia serving same DB as \node{ejabberd@first}. - You can check this running ``\verb|mnesia:info().|'' command. You + + This will start Mnesia serving the same database as \node{ejabberd@first}. + You can check this by running the command ``\verb|mnesia:info().|''. You should see a lot of remote tables and a line like the following: \begin{verbatim} running db nodes = [ejabberd@first, ejabberd@second] \end{verbatim} - + \item Now run the following in the same ``\shell{erl}'' session: \begin{verbatim} mnesia:change_table_copy_type(schema, node(), disc_copies). \end{verbatim} - This will create local disc storage for DB. - + This will create local disc storage for the database. + (alt) Change storage type of `\term{scheme}' table to ``RAM and disc - copy'' on second node via web interface. + copy'' on the second node via the web interface. + - \item Now you can add replicas of various tables to this node with ``\verb|mnesia:add_table_copy|'' or ``\verb|mnesia:change_table_copy_type|'' as above (just replace ``\verb|schema|'' with another table name and ``\verb|disc_copies|'' can be replaced with ``\verb|ram_copies|'' or ``\verb|disc_only_copies|''). - - What tables to replicate is very depend on your needs, you can get - some hints from ``\verb|mnesia:info().|'' command, by looking at - size of tables and default storage type for each table on 'first'. - - Replicating of table makes lookup in this table faster on this node, - but writing will be slower. And of course if machine with one of - replicas is down, other replicas will be used. - - Also section 5.3 (Table Fragmentation) of - \footahref{http://www.erlang.se/doc/doc-5.4/lib/mnesia-4.2/doc/html/index.html} - {Mnesia Reference Manual} can be useful. - + + Which tables to replicate is very dependant on your needs, you can get + some hints from the command ``\verb|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 \footahref{http://www.erlang.se/doc/doc-5.4.9/lib/mnesia-4.2.2/doc/html/Mnesia\_chap5.html\#5.3} + {section 5.3 (Table Fragmentation) of Mnesia User's Guide} can be helpful. + % The above URL needs update every Erlang release! + (alt) Same as in previous item, but for other tables. - + \item Run ``\verb|init:stop().|'' or just ``\verb|q().|'' to exit from - erlang shell. This probably can take some time if mnesia is not yet - transfer and process all data it needed from \term{first}. + the Erlang shell. This probably can take some time if Mnesia has not yet + transfered and processed all data it needed from \term{first}. - -\item Now run ejabberd on \term{second} with almost the same config as + +\item Now run \ejabberd{} on \term{second} with almost the same config as on \term{first} (you probably don't need to duplicate ``\verb|acl|'' and ``\verb|access|'' options --- they will be taken from \term{first}, and \verb|mod_muc| and \verb|mod_irc| should be - enabled only on one machine in cluster). + enabled only on one machine in the cluster). \end{enumerate} You can repeat these steps for other machines supposed to serve this domain. +% TODO +% See also the section about ejabberdctl!!!! +%\section{Backup and Restore} +%\label{sec:backup} +%\ind{backup} \appendix{} \section{Built-in Modules} \label{sec:modules} +\ind{modules} \subsection{Common Options} \label{sec:modcommonopts} -The following options are used by many modules, so they are described in -separate section. +The following options are used by many modules. Therefore, they are described in +this separate section. \subsubsection{\option{iqdisc}} \label{sec:modiqdiscoption} +\ind{options!iqdisc} Many modules define handlers for processing IQ queries of different namespaces -to this server or to user (e.\,g.\ to \jid{example.org} or to -\jid{user@example.org}). This option defines processing discipline of -these queries. Possible values are: +to this server or to a user (e.\,g.\ to \jid{example.org} or to +\jid{user@example.org}). This option defines processing discipline for +these queries. Possible values are: \begin{description} -\titem{no\_queue} All queries of namespace with this processing - discipline processed immediately. This also means that no other packets can - be processed until finished this. Hence this discipline is not recommended - if processing of query can take relatively long time. -\titem{one\_queue} In this case created separate queue for processing - of IQ queries of namespace with this discipline, and processing of this queue - is done in parallel with processing of other packets. This discipline is most - recommended. -\titem{parallel} In this case for all packets with this discipline - spawned separate Erlang process, so all these packets processed in parallel. - Although spawning of Erlang process have relatively low cost, this can broke - server normal work, because Erlang emulator have limit on number of processes - (32000 by default). +\titem{no\_queue} All queries of a namespace with this processing discipline are + processed immediately. This also means that no other packets can be processed + until this one has been completely processed. Hence this discipline is not + recommended if the processing of a query can take a relatively long time. +\titem{one\_queue} In this case a separate queue is created for the processing + of IQ queries of a namespace with this discipline. In addition, the processing + of this queue is done in parallel with that of other packets. This discipline + is most recommended. +\titem{parallel} For every packet with this discipline a separate Erlang process + is spawned. Consequently, all these packets are processed in parallel. + Although spawning of Erlang process has a relatively low cost, this can break + the server's normal work, because the Erlang emulator has a limit on the + number of processes (32000 by default). \end{description} Example: @@ -918,13 +1129,29 @@ Example: ]}. \end{verbatim} -\subsubsection{\option{host}} -\label{sec:modhostoption} +\subsubsection{\option{hosts}} +\label{sec:modhostsoption} +\ind{options!hosts} -This option explicitly defines hostname for the module which acts as a service. +A module acting as a service can have one or more hostnames. These hostnames +can be defined with the \option{hosts} option. -Example: -\begin{verbatim} +Examples: +\begin{itemize} +\item Serving the \ind{modules!\modecho{}}echo module on one domain: + \begin{itemize} + \item + \begin{verbatim} + {modules, + [ + ... + {mod_echo, [{hosts, ["echo.example.org"]}]}, + ... + ]}. +\end{verbatim} + \item Backwards compatibility with older ejabberd versions can be retained + with: + \begin{verbatim} {modules, [ ... @@ -932,63 +1159,61 @@ Example: ... ]}. \end{verbatim} - -\subsubsection{\option{hosts}} -\label{sec:modhostsoption} - -This option explicitly defines a list of hostnames for the module which acts as -a service. - -Example: -\begin{verbatim} + \end{itemize} + \item Serving the echo module on tho domains: + \begin{verbatim} {modules, [ ... - {mod_echo, [{hosts, ["echo.example.org", "echo.example.com"]}]}, + {mod_echo, [{hosts, ["echo.one.org", "echo.two.org"]}]}, ... ]}. \end{verbatim} - +\end{itemize} \subsection{\modannounce{}} \label{sec:modannounce} - -This module adds support for broadcast announce messages and MOTD. -When the module is loaded, it handles messages sent to the following JID's -(suppose that main server has address \jid{example.org}): +\ind{modules!\modannounce{}}\ind{MOTD}\ind{message of the day}\ind{announcements} + +This module enables configured users to broadcast announcements and to set +the message of the day (MOTD). Configured users can do these actions with their +\Jabber{} client by sending messages to specific JIDs. These JIDs are listed in +next paragraph. The first JID in each entry will apply only to the virtual host +\jid{example.org}, while the JID between brackets will apply to all virtual +hosts: \begin{description} -\titem{example.org/announce/all} Message is sent to all registered users at -\jid{example.org}. If the user is online and connected to several resources, -only resource with the highest priority will receive the message. If the -registered user is not connected, the message will be stored offline (if -oflline storage is available). -\titem{example.org/announce/online} Message is sent to all connected users at -\jid{example.org}. If the user is online and connected to several resources, -all resources will receive the message. -\titem{example.org/announce/all-hosts/online} Message is sent to all connected -users at every virtual host. If the user is online and connected to several -resources, all resources will receive the message. -\titem{example.org/announce/motd} Message is set as MOTD (Message of the Day) -and is sent to users at \jid{example.org} as they login. In addition the -message is sent to all connected users (similar to \term{announce/online} -resource). -\titem{example.org/announce/motd/update} Message is set as MOTD (Message of the -Day) and is sent to users at \jid{example.org} as they login. The message -is \emph{not sent} to all connected users. -\titem{example.org/announce/motd/delete} Any message sent to this JID -removes existing MOTD. +\titem{example.org/announce/all (example.org/announce/all-hosts/all)} The + message is sent to all registered users. If the user is online and connected + 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 \ind{modules!\modoffline{}}offline storage + (see section~\ref{sec:modoffline}) is enabled. +\titem{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. +\titem{example.org/announce/motd (example.org/announce/all-hosts/motd)}The + message is set as the message of the day (MOTD) and is sent to users when they + login. In addition the message is sent to all connected users (similar to + \term{announce/online}). +\titem{example.org/announce/motd/update (example.org/announce/all-hosts/motd/update)} + The message is set as message of the day (MOTD) and is sent to users when they + login. The message is \emph{not sent} to any currently connected user. +\titem{example.org/announce/motd/delete (example.org/announce/all-hosts/motd/delete)} + Any message sent to this JID removes the existing message of the day (MOTD). \end{description} Options: \begin{description} -\titem{access} Specifies who is allowed to send announce messages -and set MOTD (default value is \term{none}). +\titem{access} \ind{options!access}This option specifies who is allowed to + send announcements and to set the message of the day (by default, nobody is + able to send such messages). \end{description} -Example: -\begin{verbatim} - % Only admins can send announcement messages: - {access, announce, [{allow, admin}]}. +Examples: +\begin{itemize} +\item Only administrators can send announcements: + \begin{verbatim} + {access, announce, [{allow, admins}]}. {modules, [ @@ -997,67 +1222,146 @@ Example: ... ]}. \end{verbatim} - - -\subsection{\modconfigure{}} -\label{sec:modconfigure} - -Options: -\begin{description} -\iqdiscitem{\ns{ejabberd:config}} -\end{description} - +\item Administrators as well as the direction can send announcements: + \begin{verbatim} + {acl, direction, {user, "big_boss", "example.org"}}. + {acl, direction, {user, "assistant", "example.org"}}. + {acl, admins, {user, "admin", "example.org"}}. + ... + {access, announce, [{allow, admins}, + {allow, direction}]}. + ... + {modules, + [ + ... + {mod_announce, [{access, announce}]}, + ... + ]}. +\end{verbatim} +\end{itemize} \subsection{\moddisco{}} \label{sec:moddisco} +\ind{modules!\moddisco{}}\ind{protocols!JEP-0030: Service Discovery}\ind{protocols!JEP-0011: Jabber Browsing}\ind{protocols!JEP-0094: Agent Information} -This module adds support for \jepref{0030} (Service Discovery). +This module adds support for Service Discovery (\jepref{0030}). With +this module enabled, services on your server can be discovered by +\Jabber{} clients. Note that \ejabberd{} has no modules with support +for the superseded Jabber Browsing (\jepref{0011}) and Agent Information +(\jepref{0094}). Accordingly, \Jabber{} clients need to have support for +the newer Service Discovery protocol if you want them be able to discover +the services you offer. Options: \begin{description} -\iqdiscitem{\ns{http://jabber.org/protocol/disco\#items} and - \ns{http://jabber.org/protocol/disco\#info}} -\titem{extra\_domains} List of domains that will be added to server - items reply +\iqdiscitem{Service Discovery (\ns{http://jabber.org/protocol/disco\#items} and + \ns{http://jabber.org/protocol/disco\#info})} +\titem{extra\_domains} \ind{options!extra\_domains}With this option, + extra domains can be added to the Service Discovery item list. \end{description} -Example: -\begin{verbatim} +Examples: +\begin{itemize} +\item To serve a link to the Jabber User Directory on \jid{jabber.org}: + \begin{verbatim} + {modules, + [ + ... + {mod_disco, [{extra_domains, ["users.jabber.org"]}]}, + ... + ]}. +\end{verbatim} +\item To serve a link to the transports on another server: + \begin{verbatim} + {modules, + [ + ... + {mod_disco, [{extra_domains, ["icq.example.com", + "msn.example.com"]}]}, + ... + ]}. +\end{verbatim} +\item To serve a link to a few friendly servers: + \begin{verbatim} {modules, [ ... - {mod_disco, [{extra_domains, ["jit.example.com", - "etc.example.com"]}]}, + {mod_disco, [{extra_domains, ["example.org", + "example.com"]}]}, ... ]}. \end{verbatim} +\end{itemize} \subsection{\modecho{}} \label{sec:modecho} +\ind{modules!\modecho{}}\ind{debugging} -This module acts as a service and simply returns to sender any \Jabber{} -packet. Module may be useful for debugging. +This module simply echoes any \Jabber{} +packet back to the sender. This mirror can be of interest for +\ejabberd{} and \Jabber{} client debugging. Options: \begin{description} \hostitem{echo} \end{description} +Examples: +\begin{itemize} +\item Mirror, mirror, on the wall, who is the most beautiful + of them all? + \begin{verbatim} + {modules, + [ + ... + {mod_echo, [{hosts, ["mirror.example.org"]}]}, + ... + ]}. +\end{verbatim} +\item If you still do not understand the inner workings of \modecho{}, + you can find a few more examples in section~\ref{sec:modhostsoption}. +\end{itemize} \subsection{\modirc{}} \label{sec:modirc} +\ind{modules!\modirc{}}\ind{IRC} -This module implements IRC transport. +This module is an IRC transport that can be used to join channels on IRC +servers. + +End user information: +\ind{protocols!groupchat 1.0}\ind{protocols!JEP-0045: Multi-User Chat} +\begin{itemize} +\item A \Jabber{} client with ``groupchat 1.0'' support or Multi-User + Chat support (\jepref{0045}) is necessary to join IRC channels. +\item 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\%\jid{irc.example.org}'' in case \jid{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. +\item You can register your nickame by sending ``IDENTIFY password'' to \\ + \jid{nickserver!irc.example.org@irc.jabberserver.org}. +\item Entering your password is possible by sending ``LOGIN nick password'' \\ + to \jid{nickserver!irc.example.org@irc.jabberserver.org}. +\item When using a popular \Jabber{} server, it can occur that no + connection can be achieved with some IRC servers because they limit the + number of conections from one IP. +\end{itemize} Options: \begin{description} \hostitem{irc} -\titem{access} Specifies who is allowed to use IRC transport (default value is \term{all}). +\titem{access} \ind{options!access}This option can be used to specify who + may use the IRC transport (default value: \term{all}). \end{description} -Example: -\begin{verbatim} +Examples: +\begin{itemize} +\item In the first example, the IRC transport is available on (all) your + virtual host(s) with the prefix ``\jid{irc.}''. Furthermore, anyone is + able to use the transport. + \begin{verbatim} {modules, [ ... @@ -1065,92 +1369,214 @@ Example: ... ]}. \end{verbatim} - +% bug in current svn!!: irc-transport.two.org will *not* show up in the service discovery items; instead you will see irc.two.org!!!! +\item In next example the IRC transport is available on two virtual hosts + with different prefixes on each host. Moreover, the transport is only + accessible by paying customers registered on our domains and on other servers. + \begin{verbatim} + {acl, paying_customers, {user, "customer1", "one.org"}}. + {acl, paying_customers, {user, "customer2", "two.org"}}. + {acl, paying_customers, {user, "customer3", "example.org"}}. + ... + {access, paying_customers, [{allow, paying_customers}, + {deny, all}]}. + ... + {modules, + [ + ... + {mod_irc, [{access, paying_customers}, + {hosts, ["irc.one.org", "irc-transport.two.org"]}]}, + ... + ]}. +\end{verbatim} +\end{itemize} \subsection{\modlast{}} \label{sec:modlast} +\ind{modules!\modlast{}}\ind{protocols!JEP-0012: Last Activity} -This module adds support for \jepref{0012} (Last Activity) +This module adds support for Last Activity (\jepref{0012}). It can be used to +discover when a disconnected user last accessed the server, to know when a +connected user was last active on the server, or to query the uptime of the +\ejabberd{} server. Options: \begin{description} -\iqdiscitem{\ns{jabber:iq:last}} +\iqdiscitem{Last activity (\ns{jabber:iq:last})} \end{description} - \subsection{\modmuc{}} \label{sec:modmuc} +\ind{modules!\modmuc{}}\ind{protocols!JEP-0045: Multi-User Chat}\ind{conferencing} + +With this module enabled, your server will support Multi-User Chat +(\jepref{0045}). End users will be able to join text conferences. Notice +that this module is not (yet) clusterable. -This module implements \jepref{0045} (Multi-User Chat) service. + +Some of the features of Multi-User Chat: +\begin{itemize} +\item Sending private messages to room participants. +\item Inviting users. +\item Setting a conference topic. +\item Creating password protected rooms. +\item Kicking and banning participants. +\end{itemize} Options: \begin{description} \hostitem{conference} -\titem{access} Specifies who is allowed to use MUC service (default value is \term{all}). -\titem{access\_create} Specifies who is allowed to create new rooms at - MUC service (default value is \term{all}). -\titem{access\_admin} Specifies who is allowed to administrate MUC service -(default value is \term{none}, which means that only creator may administer her room). +\titem{access} \ind{options!access}You can specify who is allowed to use + the Multi-User Chat service (by default, everyone is allowed to use it). +\titem{access\_create} \ind{options!access\_create}To configure who is + allowed to create new rooms at the Multi-User Chat service, this option + can be used (by default, everybody is allowed to create rooms). +\titem{access\_admin} \ind{options!access\_admin}This option specifies + who is allowed to administrate the Multi-User Chat service (the default + value is \term{none}, which means that only the room creator can + administer his room). \end{description} -Example: -\begin{verbatim} - % Define admin ACL - {acl, admin, {user, "admin"}} - - % Define MUC admin access rule - {access, muc_admin, [{allow, admin}]} - +Examples: +\begin{itemize} +\item 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 + \jid{admin@example.org} is allowed to administrate any room. In this + example he is also a global administrator. + \begin{verbatim} + {acl, admins, {user, "admin", "example.org"}}. + ... + {access, muc_admins, [{allow, admins}]}. + ... {modules, [ ... {mod_muc, [{access, all}, {access_create, all}, - {access_admin, muc_admin}]}, + {access_admin, muc_admins}]}, ... ]}. \end{verbatim} - +\item In the second example the Multi-User Chat service is only accessible by + 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. + \begin{verbatim} + {acl, paying_customers, {user, "customer1", "one.org"}}. + {acl, paying_customers, {user, "customer2", "two.org"}}. + {acl, paying_customers, {user, "customer3", "example.org"}}. + {acl, admins, {user, "admin", "example.org"}}. + ... + {access, muc_admins, [{allow, admins}, + {deny, all}]}. + {access, muc_access, [{allow, paying_customers}, + {allow, admins}, + {deny, all}]}. + ... + {modules, + [ + ... + {mod_muc, [{access, muc_access}, + {access_create, muc_admins}, + {access_admin, muc_admins}]}, + ... + ]}. +\end{verbatim} +\end{itemize} \subsection{\modoffline{}} \label{sec:modoffline} +\ind{modules!\modoffline{}} -This module implements offline message storage. - +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 +\term{ejabberdctl}\ind{ejabberdctl} has a command to delete expired messages +(see section~\ref{sec:ejabberdctl}). \subsection{\modprivacy{}} \label{sec:modprivacy} +\ind{modules!\modprivacy{}}\ind{Blocking Communication}\ind{Privacy Rules}\ind{protocols!RFC 3921: XMPP IM} -This module implements Privacy Rules as defined in XMPP IM -(see \ahrefurl{http://www.jabber.org/ietf/}). +This module implements Blocking Communication (also known as Privacy Rules) +as defined in section 10 from XMPP IM. If end users have support for it in +their \Jabber{} client, they will be able to: +\begin{quote} +\begin{itemize} +\item Retrieving one's privacy lists. +\item Adding, removing, and editing one's privacy lists. +\item Setting, changing, or declining active lists. +\item Setting, changing, or declining the default list (i.e., the list that + is active by default). +\item Allowing or blocking messages based on JID, group, or subscription type + (or globally). +\item Allowing or blocking inbound presence notifications based on JID, group, + or subscription type (or globally). +\item Allowing or blocking outbound presence notifications based on JID, group, + or subscription type (or globally). +\item Allowing or blocking IQ stanzas based on JID, group, or subscription type + (or globally). +\item Allowing or blocking all communications based on JID, group, or + subscription type (or globally). +\end{itemize} +(from \ahrefurl{http://www.xmpp.org/specs/rfc3921.html\#privacy}) +\end{quote} Options: \begin{description} -\iqdiscitem{\ns{jabber:iq:privacy}} +\iqdiscitem{Blocking Communication (\ns{jabber:iq:privacy})} \end{description} - \subsection{\modprivate{}} \label{sec:modprivate} +\ind{modules!\modprivate{}}\ind{protocols!JEP-0049: Private XML Storage}\ind{protocols!JEP-0048: Bookmark Storage} -This module adds support of \jepref{0049} (Private XML Storage). +This module adds support for Private XML Storage (\jepref{0049}): +\begin{quote} +Using this method, Jabber entities can store private data on the server and +retrieve it whenever necessary. The data stored might be anything, as long as +it is valid XML. One typical usage for this namespace is the server-side storage +of client-specific preferences; another is Bookmark Storage (\jepref{0048}). +\end{quote} Options: \begin{description} -\iqdiscitem{\ns{jabber:iq:private}} +\iqdiscitem{Private XML Storage (\ns{jabber:iq:private})} \end{description} - \subsection{\modpubsub{}} \label{sec:modpubsub} +\ind{modules!\modpubsub{}}\ind{protocols!JEP-0060: Publish-Subscribe} + +This module offers a Publish-Subscribe Service (\jepref{0060}). +Publish-Subscribe can be used to develop (examples are taken from the JEP): +\begin{quote} +\begin{itemize} +\item news feeds and content syndacation, +\item avatar management, +\item shared bookmarks, +\item auction and trading systems, +\item online catalogs, +\item workflow systems, +\item network management systems, +\item NNTP gateways, +\item vCard/profile management, +\item and weblogs. +\end{itemize} +\end{quote} -This module implements \jepref{0060} (Publish-Subscribe Service). +\ind{J-EAI}\ind{EAI}\ind{ESB}\ind{Enterprise Application Integration}\ind{Enterprise Service Bus} +Another example is \footahref{http://www.process-one.net/en/projects/j-eai/}{J-EAI}. +This is an XMPP-based Enterprise Application Integration (EAI) platform (also +known as ESB, the Enterprise Service Bus). The J-EAI project builts upon +\ejabberd{}'s codebase and has contributed several features to \modpubsub{}. Options: \begin{description} \hostitem{pubsub} -\titem{served\_hosts} Specifies which hosts are served by the service. -If absent then only main \ejabberd{} host is served. +\titem{served\_hosts} \ind{options!served\_hosts}To specify which hosts needs to + be served, you can use this option. If absent, only the main \ejabberd{} + host is served. % Not a straigtforward description! This needs to be improved! \end{description} Example: @@ -1164,31 +1590,41 @@ Example: ]}. \end{verbatim} - \subsection{\modregister{}} \label{sec:modregister} +\ind{modules!\modregister{}}\ind{protocols!JEP-0077: In-Band Registration}\ind{public registration} + +This module adds support for In-Band Registration (\jepref{0077}). This protocol +enables end users to use a \Jabber{} client to: +\begin{itemize} +\item Register a new account on the server. +\item Change the password from an existing account on the server. +\item Delete an existing account on the server. +\end{itemize} -This module adds support for \jepref{0077} (In-Band Registration). Options: \begin{description} -\titem{access} Specifies rule to restrict registration. -If this rule returns ``deny'' on requested user name, then -registration is not allowed for it. (default value is \term{all}, which means -no restrictions). -\iqdiscitem{\ns{jabber:iq:register}} +\titem{access} \ind{options!access}This option can be configured to specify + 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). +\iqdiscitem{In-Band Registration (\ns{jabber:iq:register})} \end{description} -Example: -\begin{verbatim} - % Deny registration for users with too short name +Examples: +\begin{itemize} +\item Next example prohibits the registration of too short account names and of + account names with exotic characters in it: + \begin{verbatim} {acl, shortname, {user_glob, "?"}}. {acl, shortname, {user_glob, "??"}}. - % Another variant: {acl, shortname, {user_regexp, "^..?$"}}. - + {acl, strangename, {user_regexp, "^..?$"}}. + ... {access, register, [{deny, shortname}, + {deny, strangename}, {allow, all}]}. - + ... {modules, [ ... @@ -1196,34 +1632,55 @@ Example: ... ]}. \end{verbatim} +\item The in-band registration of new accounts can be prohibited by changing the + \option{access} option. If you really want to disable all In-Band Registration + functionality, that is changing passwords in-band and deleting accounts + in-band, you have to remove \modregister{} from the modules list. In this + example all In-Band Registration functionality is disabled: + \begin{verbatim} + {access, register, [{deny, all}]}. + {modules, + [ + ... +% {mod_register, [{access, register}]}, + ... + ]}. +\end{verbatim} +\end{itemize} \subsection{\modroster{}} \label{sec:modroster} +\ind{modules!\modroster{}}\ind{roster management}\ind{protocols!RFC 3921: XMPP IM} -This module implements roster management. +This module implements roster management as defined in \footahref{http://www.xmpp.org/specs/rfc3921.html\#roster}{RFC 3921: XMPP IM}. Options: \begin{description} -\iqdiscitem{\ns{jabber:iq:roster}} +\iqdiscitem{Roster Management (\ns{jabber:iq:roster})} \end{description} - \subsection{\modservicelog{}} \label{sec:modservicelog} +\ind{modules!\modservicelog{}}\ind{message auditing}\ind{Bandersnatch} -This module adds support for logging of user packets via any jabber service. -These packets encapsulated in <route/> element and sended to specified -services. +This module adds support for logging end user packets via a \Jabber{} message +auditing service such as +\footahref{http://www.funkypenguin.co.za/bandersnatch/}{Bandersnatch}. All user +packets are encapsulated in a \verb|<route/>| element and sent to the specified +service(s). Options: \begin{description} - \titem{loggers} Specifies a list of services which will receive users - packets. +\titem{loggers} \ind{options!loggers}With this option a (list of) service(s) + that will receive the packets can be specified. \end{description} -Example: -\begin{verbatim} +Examples: +\begin{itemize} +\item To log all end user packets to the Bandersnatch service running on + \jid{bandersnatch.example.com}: + \begin{verbatim} {modules, [ ... @@ -1231,171 +1688,258 @@ Example: ... ]}. \end{verbatim} - +\item To log all end user packets to the Bandersnatch service running on + \jid{bandersnatch.example.com} and the backup service on + \jid{bandersnatch.example.org}: + \begin{verbatim} + {modules, + [ + ... + {mod_service_log, [{loggers, ["bandersnatch.example.com", + "bandersnatch.example.org"]}]}, + ... + ]}. +\end{verbatim} +\end{itemize} \subsection{\modsharedroster{}} \label{sec:modsharedroster} +\ind{modules!\modsharedroster{}}\ind{shared roster groups} -This module implements shared roster groups support. +This module enables you to create shared roster groups. This means that you can +create groups of people that can see members from (other) groups in their +rosters. The big advantages of this feature are that end users do not need to +manually add all users to their rosters, and that they cannot permanently delete +users from the shared roster groups. -You can edit shared roster groups via web-interface. Each group has an unique -ID and the following parameters: +Shared roster groups can be edited \emph{only} via the web interface. Each group +has a unique identification and the following parameters: \begin{description} -\item[Name] The name of the group, which will be displayed in roster. -\item[Description] Textual description of this group, doesn't affect anything. -\item[Members] List of full JIDs of group members, entered one per line in - web-interface. -\item[Displayed groups] List of IDs of groups which will be in rosters of this - group members. +\item[Name] The name of the group, which will be displayed in the roster. +\item[Description] The description of the group. This parameter doesn't affect + anything. +\item[Members] A list of full JIDs of group members, entered one per line in + the web interface. +\item[Displayed groups] A list of groups that will be in the rosters of this + group's members. \end{description} -For example, to have a group of users which can see each other in roster, -create a group like on table~\ref{tab:srge1}. -\begin{table}[htbp] +Examples: +\begin{itemize} +\item Take the case of a computer club that wants all its members seeing each + other in their rosters. To achieve this, they need to create a shared roster + group similar to next table: +\begin{table}[H] \centering \begin{tabular}{|l|l|} - & Group `\texttt{users}'\\ - Name& Users\\ - Members& + \hline Identification& Group `\texttt{club\_members}'\\ + \hline Name& Club Members\\ + \hline Description& Members from the computer club\\ + \hline Members& {\begin{tabular}{l} - \jid{user1@example.org}\\ - \jid{user2@example.org}\\ - \jid{user3@example.org} + \jid{member1@example.org}\\ + \jid{member2@example.org}\\ + \jid{member3@example.org} \end{tabular} }\\ - Displayed groups& \texttt{users} + \hline Displayed groups& \texttt{club\_members}\\ + \hline \end{tabular} - \caption{Shared group example N1} - \label{tab:srge1} \end{table} - -To have 3 groups `\texttt{managers}', `\texttt{workgroup1}', and -`\texttt{workgroup2}', where group `\texttt{managers}' can see members of all -groups, and other two groups can see `\texttt{managers}' group and themselves, -create groups like on table~\ref{tab:srge2}. -\begin{table}[htbp] +\item In another case we have a company which has three divisions: Management, + Marketing and Sales. All group members should see all other members in their + rosters. Additonally, all managers should have all marketing and sales people + in their roster. Simultaneously, all marketeers and the whole sales team + should see all managers. This scenario can be achieved by creating shared + roster groups as shown in the following table: +\begin{table}[H] \centering \begin{tabular}{|l|l|l|l|} - & - Group `\texttt{managers}'& - Group `\texttt{workgroup1}'& - Group `\texttt{workgroup2}'\\ - Name& Managers& Workgroup1& Workgroup2\\ + \hline Identification& + Group `\texttt{management}'& + Group `\texttt{marketing}'& + Group `\texttt{sales}'\\ + \hline Name& Management& Marketing& Sales\\ + \hline Description& \\ Members& {\begin{tabular}{l} \jid{manager1@example.org}\\ \jid{manager2@example.org}\\ - \jid{manager3@example.org} + \jid{manager3@example.org}\\ + \jid{manager4@example.org} \end{tabular} }& {\begin{tabular}{l} - \jid{user1@example.org}\\ - \jid{user2@example.org}\\ - \jid{user3@example.org} + \jid{marketeer1@example.org}\\ + \jid{marketeer2@example.org}\\ + \jid{marketeer3@example.org}\\ + \jid{marketeer4@example.org} \end{tabular} }& {\begin{tabular}{l} - \jid{user4@example.org}\\ - \jid{user5@example.org}\\ - \jid{user6@example.org} + \jid{saleswoman1@example.org}\\ + \jid{salesman1@example.org}\\ + \jid{saleswoman2@example.org}\\ + \jid{salesman2@example.org} \end{tabular} }\\ - Displayed groups& + \hline Displayed groups& {\begin{tabular}{l} - \texttt{managers}\\ - \texttt{workgroup1}\\ - \texttt{workgroup2} + \texttt{management}\\ + \texttt{marketing}\\ + \texttt{sales} \end{tabular} }& {\begin{tabular}{l} - \texttt{managers}\\ - \texttt{workgroup1} + \texttt{management}\\ + \texttt{marketing} \end{tabular} }& {\begin{tabular}{l} - \texttt{managers}\\ - \texttt{workgroup2} + \texttt{management}\\ + \texttt{sales} \end{tabular} - } + }\\ + \hline \end{tabular} - \caption{Shared group example N2} - \label{tab:srge2} \end{table} +\end{itemize} \subsection{\modstats{}} \label{sec:modstats} +\ind{modules!\modstats{}}\ind{protocols!JEP-0039: Statistics Gathering}\ind{statistics} -This module adds support for \jepref{0039} (Statistics Gathering). +This module adds support for Statistics Gathering (\jepref{0039}). This protocol +allows you to retrieve next statistics from your \ejabberd{} deployment: +\begin{itemize} +\item Total number of registered users on the current virtual host (users/total). +\item Total number of registered users on all virtual hosts (users/all-hosts/total). +\item Total number of online users on the current virtual host (users/online). +\item Total number of online users on all virtual hosts (users/all-hosts/online). +\end{itemize} Options: \begin{description} -\iqdiscitem{\ns{http://jabber.org/protocol/stats}} +\iqdiscitem{Statistics Gathering (\ns{http://jabber.org/protocol/stats})} \end{description} +As there are only a small amount of clients (for \ind{Tkabber}example +\footahref{http://tkabber.jabber.ru/}{Tkabber}) and software libraries with +support for this JEP, a few examples are given of the XML you need to send +in order to get the statistics. Here they are: +\begin{itemize} +\item You can request the number of online users on the current virtual host + (\jid{example.org}) by sending: + \begin{verbatim} +<iq to='example.org' type='get'> + <query xmlns='http://jabber.org/protocol/stats'> + <stat name='users/online'/> + </query> +</iq> +\end{verbatim} +\item You can request the total number of registered users on all virtual hosts + by sending: + \begin{verbatim} +<iq to='example.org' type='get'> + <query xmlns='http://jabber.org/protocol/stats'> + <stat name='users/all-hosts/total'/> + </query> +</iq> +\end{verbatim} +\end{itemize} \subsection{\modtime{}} \label{sec:modtime} +\ind{modules!\modtime{}}\ind{protocols!JEP-0090: Entity Time} -This module answers UTC time on \ns{jabber:iq:time} queries. +This module features support for Entity Time (\jepref{0090}). By using this JEP, +you are able to discover the time at another entity's location. Options: \begin{description} -\iqdiscitem{\ns{jabber:iq:time}} +\iqdiscitem{Entity Time (\ns{jabber:iq:time})} \end{description} - \subsection{\modvcard{}} \label{sec:modvcard} +\ind{modules!\modvcard{}}\ind{JUD}\ind{Jabber User Directory}\ind{vCard}\ind{protocols!JEP-0054: vcard-temp} -This module implements simple Jabber User Directory (based on user vCards) -and answers server vCard on \ns{vcard-temp} queries. +This module allows end users to store and retrieve their vCard, and to retrieve +other users vCards, as defined in vcard-temp (\jepref{0054}). The module also +implements an uncomplicated \Jabber{} User Directory based on the vCards of +these users. Moreover, it enables the server to send its vCard when queried. Options: \begin{description} \hostitem{vjud} \iqdiscitem{\ns{vcard-temp}} -\titem{search} Specifies whether search is enabled (value is \term{true}, default) or -disabled (value is \term{false}) by the service. If \term{search} is set to \term{false}, -option \term{host} is ignored and service does not appear in Jabber Discovery items. -\titem{matches} Limits the number of reported search results. If value is set to -\term{infinity} then all search results are reported. Default value is \term{30}. -\titem{allow\_return\_all} Specifies whether search with empty input fields can -return all known users. Default is \term{false}. -\titem{search\_all\_hosts} If set in \term{true} then search returns matched -items at all virtual hosts. Otherwise only current host items are returned. -Default is \term{true}. +\titem{search} \ind{options!search}This option specifies whether the search + functionality is enabled (value: \term{true}) or disabled + (value: \term{false}). If disabled, the option \term{hosts} will be + ignored and the \Jabber{} User Directory service will not appear in the + Service Discovery item list. The default value is \term{true}. +\titem{matches} \ind{options!matches}With this option, the number of reported + search results can be limited. If the option's value is set to \term{infinity}, + all search results are reported. The default value is \term{30}. +\titem{allow\_return\_all} \ind{options!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 + \term{false}. +\titem{search\_all\_hosts} \ind{options!search\_all\_hosts}If this option is + set to \term{true}, search operations will apply to all virtual hosts. + Otherwise only the current host will be searched. The default value is + \term{true}. \end{description} -Example: -\begin{verbatim} +Examples: +\begin{itemize} +\item In this first situation, search results are limited to twenty items, + every user who added information to their vCard will be listed when people + do an empty search, and only users from the current host will be returned: + \begin{verbatim} {modules, [ ... {mod_vcard, [{search, true}, {matches, 20}, {allow_return_all, true}, - {search_all_hosts, false}]} + {search_all_hosts, false}]}, ... ]}. \end{verbatim} - +\item The second situation differs in a way that search results are not limited, + and that all virtual hosts will be searched instead of only the current one: + \begin{verbatim} + {modules, + [ + ... + {mod_vcard, [{search, true}, + {matches, infinity}, + {allow_return_all, true}]}, + ... + ]}. +\end{verbatim} +\end{itemize} \subsection{\modversion{}} \label{sec:modversion} +\ind{modules!\modversion{}}\ind{protocols!JEP-0092: Software Version} -This module answers \ejabberd{} version on \ns{jabber:iq:version} queries. +This module implements Software Version (\jepref{0092}). Consequently, it +answers \ejabberd{}'s version when queried. Options: \begin{description} -\iqdiscitem{\ns{jabber:iq:version}} +\iqdiscitem{Software Version (\ns{jabber:iq:version})} \end{description} -\section{I18n/L10n} +\section{Internationalization and Localization} \label{sec:i18nl10n} +\ind{xml:lang}\ind{internationalization}\ind{localization}\ind{i18n}\ind{l10n} -All built-in modules support \texttt{xml:lang} attribute inside IQ queries. -E.\,g.\ on figure~\ref{fig:discorus} showed the reply on the following query: +All built-in modules support the \texttt{xml:lang} attribute inside IQ queries. +Figure~\ref{fig:discorus}, for example, shows the reply to the following query: \begin{verbatim} <iq id='5' to='example.org' @@ -1408,20 +1952,90 @@ E.\,g.\ on figure~\ref{fig:discorus} showed the reply on the following query: \begin{figure}[htbp] \centering \insimg{discorus.png} - \caption{Discovery result when \texttt{xml:lang='ru'}} + \caption{Service Discovery when \texttt{xml:lang='ru'}} \label{fig:discorus} \end{figure} -Also web-interface supports \verb|Accept-Language| HTTP header (see -figure~\ref{fig:webadmmainru}, compare it with figure~\ref{fig:webadmmain}) +The web interface also supports the \verb|Accept-Language| HTTP header (compare +figure~\ref{fig:webadmmainru} with figure~\ref{fig:webadmmain}) \begin{figure}[htbp] \centering \insimg{webadmmainru.png} - \caption{Web-administration top page with HTTP header - ``\verb|Accept-Language: ru|''} + \caption{Top page from the web interface with HTTP header + ``Accept-Language: ru''} \label{fig:webadmmainru} \end{figure} +\newpage +\section{Release Notes} +\label{sec:releasenotes} +\ind{release notes} + +\subsection{ejabberd 0.9} +\verbatiminput{release_notes_0.9.txt} + +\subsection{ejabberd 0.9.1} +\verbatiminput{release_notes_0.9.1.txt} + +\subsection{ejabberd 0.9.8} +\verbatiminput{release_notes_0.9.8.txt} + + +\section{Acknowledgements} +\label{sec:acknowledgements} +\ind{acknowledgements} +Thanks to all people who contributed to this guide: +\begin{itemize} +\item Alexey Shchepin (\ahrefurl{xmpp:aleksey@jabber.ru}) +\item Florian Zumbiehl (\ahrefurl{xmpp:florz@florz.de}) +\item Michael Grigutsch (\ahrefurl{xmpp:migri@jabber.i-pobox.net}) +\item Micka\"el R\'emond (\ahrefurl{xmpp:mremond@erlang-projects.org}) +\item Sander Devrieze (\ahrefurl{xmpp:sander@devrieze.dyndns.org}) +\item Sergei Golovan (\ahrefurl{xmpp:sgolovan@nes.ru}) +\item Vsevolod Pelipas (\ahrefurl{xmpp:vsevoload@jabber.ru}) +\end{itemize} + +% TODO +%\section{Glossary} +%\label{sec:glossary} +%\ind{glossary} + +%\begin{description} +%\titem{c2s} +%\titem{s2s} +%\titem{STARTTLS} +%\titem{JEP} (\Jabber{} Enhancement Proposal) +%\titem{Resource} +%\titem{Roster} +%\titem{Transport} +%\titem{JID} (\Jabber{} ID) <Wikipedia> +%\titem{JUD} (\Jabber{} User Directory) +%\titem{vCard} <Wikipedia> +%\titem{Publish-Subscribe} +%\titem{Namespace} +%\titem{Erlang} <Wikipedia> +%\titem{Fault-tolerant} +%\titem{Distributed} <Wikipedia> +%\titem{Node} <Wikipedia> +%\titem{Tuple} <Wikipedia> +%\titem{Regular Expression} +%\titem{ACL} (Access Control List) <Wikipedia> +%\titem{IPv6} <Wikipedia> +%\titem{XDB} ??? +%\titem{LDAP} (Lightweight Directory Access Protocol) <Wikipedia> +%\titem{ODBC} (Open Database Connectivity) <Wikipedia> +%\titem{Virtual Hosting} <Wikipedia> +%\titem{} +%\titem{} + +%\end{description} + + + +% Remove the index from the HTML version to save size and bandwith. +\begin{latexonly} +\printindex +\end{latexonly} \end{document} diff --git a/doc/introduction.tex b/doc/introduction.tex new file mode 100644 index 000000000..fc61f24ad --- /dev/null +++ b/doc/introduction.tex @@ -0,0 +1,131 @@ +\section{Introduction} +\label{sec:intr} + +\quoting{I just tried out ejabberd and was impressed both by ejabberd itself and the language it is written in, Erlang. -- +Joeri} + +\ejabberd{} is a free (GPL) distributed fault-tolerant \Jabber{}/XMPP server and is mainly written in \footahref{http://www.erlang.org/}{Erlang}. + +\ejabberd{} is designed to be a \marking{stable} and \marking{feature rich} \Jabber{}/XMPP server. + +\ejabberd{} is suitable for small servers, whether they need to be scalable or not, as well as extremely big servers. + +%\subsection{Layout with example deployment (title needs a better name)} + +%In this section there will be a graphical overview like these:\\ +%\verb|http://www.tipic.com/var/timp/timp_dep.gif| \\ +%\verb|http://www.jabber.com/images/jabber_Com_Platform.jpg| \\ +%\verb|http://www.antepo.com/files/OPN45systemdatasheet.pdf| \\ + +%Some small images of Jabber clients that are known to work greatly with ejabberd. Less text!!! + +%\subsection{Try It Today} + +%(Not sure if I will include/finish this section for the next version.) + +%\begin{itemize} +%\item Erlang REPOS +%\item Packages in distributions +%\item Windows binary +%\item source tar.gz +%\item Migration from Jabberd14 (and so also Jabberd2 because you can migrate from version 2 back to 14) and Jabber Inc. XCP possible. +%\end{itemize} + +\newpage +\subsection{Key Features} +\label{sec:keyfeatures} +\ind{features!key features} + +\quoting{Erlang seems to be tailor-made for writing stable, robust servers. -- +Peter Saint-Andr\'e, Executive Director of the Jabber Software Foundation} + +\ejabberd{} is: +\begin{itemize} +\item \marking{Multiplatform:} \ejabberd{} runs under Windows NT/2000/XP and Unix derived systems such as Linux, FreeBSD and NetBSD. + +\item \marking{Distributed:} You can run \ejabberd{} on a cluster of machines and all of them will serve one \Jabber{} domain. 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 hundreds of concurrent users. + +\item \marking{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''. + +\item \marking{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 installed, and ready to run out of the box. Other benefits for administrators include: +\begin{itemize} +\item Comprehensive documentation.\moreinfo{ --- You can start in the \footahref{http://ejabberd.jabber.ru/book}{ejabberd Book}.} +\item Straightforward installers for Windows and Linux.\moreinfo{ --- (\footahref{http://ejabberd.jabber.ru/screenshots-linux-installer}{Screenshots}).} +\item Web interface for administration tasks.\moreinfo{ --- With HTTPS secure access. \footahref{http://ejabberd.jabber.ru/online-demo-webadmin}{Demo}.} +\item Shared Roster groups.\improved{}\moreinfo{ --- The administrator can setup a common list of \Jabber{} users for all users on the server. Those users are virtually added to all rosters. They cannot be removed, but can be renamed or moved into different roster groups. Does not require client implementation. Not related to \jepref{0144} (Roster Item Exchange).\footahref{http://ejabberd.jabber.ru/screenshots-shared-roster-groups}{Screenshots})} +\item Command line administration tool.\moreinfo{ --- Some basic administration tasks can be acomplished using the command line: register/remove users, backup/restore database, amongst others (\footahref{http://ejabberd.jabber.ru/screenshots-administration#ejabberdctl}{Screenshots}).} +\item Can integrate with existing authentication mechanisms. +\item Capability to send announce messages. +\item Statistics via \jepref{0039} (Statistics Gathering). +\end{itemize} + +\item \marking{Internationalized:} \ejabberd{} leads in internationalization. Hence it is very well suited in a globalized world. Related features are: + +\begin{itemize} +\item Translated in 11 languages.\moreinfo{ --- More information is available \footahref{http://ejabberd.jabber.ru/localization}{here}.} +\item Support for \footahref{http://www.ietf.org/rfc/rfc3490.txt}{IDNA}. +\item Support for \ns{xml:lang}. +\end{itemize} + +\item \marking{Modular:} \ejabberd{}'s modular architecture allows easy customization: +\begin{itemize} +\item Load only the modules you want. +\item Extend \ejabberd{} with your own custom modules.\moreinfo{ --- A list of contributed modules and patches is available on the \footahref{http://ejabberd.jabber.ru/contributions}{contributions page}.} +\end{itemize} + + +\end{itemize} + +\newpage + +\subsection{Additional Features} +\label{sec:addfeatures} +\ind{features!additional features} + +\quoting{ejabberd is making inroads to solving the "buggy incomplete server" problem -- +Justin Karneges, Founder of the Psi and the Delta projects} + +Besides common \Jabber{} server features, \ejabberd{} comes with a wide range of other features: +\begin{itemize} +\item The ability to interface via external components with networks such as: +\begin{itemize} +\item AIM +\item ICQ +\item MSN +\item Yahoo! +\end{itemize} +\item Open Standards +\begin{itemize} +\item \footahref{http://ejabberd.jabber.ru/protocols}{Many JEPs supported}. +\item XML-based protocol +\item Fully XMPP compliant for c2s connections (Core \& IM) \moreinfo{ --- ejabberd supports all XMPP Core 1.0 and XMPP IM 1.0, or is close to it. Check the \footahref{http://ejabberd.jabber.ru/protocols}{supported protocols}.} +\end{itemize} +\item Security +\begin{itemize} +\item SASL and STARTTLS for c2s connections. +\item STARTTLS and Dialback s2s connections.\new{} +\item Obsolete SSL for c2s connections also supported. +\item Web interface accessible via HTTPS secure access. +\end{itemize} +\item Databases +\begin{itemize} +\item Mnesia. +\item ODBC data storage support (tested against PostgreSQL). \moreinfo{ --- ODBC requests can be load balanced between several connections.} +\end{itemize} +\item Authentication +\begin{itemize} +\item LDAP. \moreinfo{ --- Accounts can authenticate in a LDAP server.} +\item External Authentication script. +\item Internal Authentication. +\end{itemize} +\item Others +\begin{itemize} +\item IPv6 support both for c2s and s2s connections. +\item Support for virtual hosting. \moreinfo{ --- Several \Jabber{} hosts can be hosted on the same \ejabberd{} instance. As simple as adding a new domain name to the list of hosts in the configuration file.} +\item \tjepref{0025}{HTTP Polling} service +\item \tjepref{0045}{Multi-User Chat} module. +\item IRC transport. +\item \tjepref{0060}{Publish-Subscribe} component. +\item Users Directory based on users vCards. +\end{itemize} +\end{itemize}
\ No newline at end of file diff --git a/doc/logo.png b/doc/logo.png Binary files differindex bb58a0e89..b8d17ebfd 100644 --- a/doc/logo.png +++ b/doc/logo.png diff --git a/doc/version.tex b/doc/version.tex new file mode 100644 index 000000000..e47eb3018 --- /dev/null +++ b/doc/version.tex @@ -0,0 +1,2 @@ +% Define ejabberd version here. +\newcommand{\version}{0.9.9-alpha}
\ No newline at end of file |
