From 1854b5e411445beeece621a4058941ba0266704d Mon Sep 17 00:00:00 2001
From: Christophe Romain <christophe.romain@process-one.net>
Date: Wed, 20 May 2015 11:43:29 +0200
Subject: Remove obsolete doc and win32 files (EJAB-1738)

---
 doc/guide.tex | 6494 ---------------------------------------------------------
 1 file changed, 6494 deletions(-)
 delete mode 100644 doc/guide.tex

(limited to 'doc/guide.tex')

diff --git a/doc/guide.tex b/doc/guide.tex
deleted file mode 100644
index 9817dc229..000000000
--- a/doc/guide.tex
+++ /dev/null
@@ -1,6494 +0,0 @@
-\documentclass[a4paper,10pt]{book}
-
-%% Packages
-\usepackage{float}
-\usepackage{graphics}
-\usepackage{hevea}
-\usepackage[pdftex,colorlinks,unicode,urlcolor=blue,linkcolor=blue,
-        pdftitle=Ejabberd\ Installation\ and\ Operation\ Guide,pdfauthor=ProcessOne,pdfsubject=ejabberd,pdfkeywords=ejabberd,
-        pdfpagelabels=false]{hyperref}
-\usepackage{makeidx}
-%\usepackage{showidx} % Only for verifying the index entries.
-\usepackage{verbatim}
-\usepackage{geometry}
-\usepackage{fancyhdr}
-
-\pagestyle{fancy}                         %Forces the page to use the fancy template
-\renewcommand{\chaptermark}[1]{\markboth{\textbf{\thechapter}.\ \emph{#1}}{}}
-\renewcommand{\sectionmark}[1]{\markright{\thesection\ \boldmath\textbf{#1}\unboldmath}}
-\fancyhf{}
-\fancyhead[LE,RO]{\textbf{\thepage}}      %Displays the page number in bold in the header,
-                                           % to the left on even pages and to the right on odd pages.
-\fancyhead[RE]{\nouppercase{\leftmark}}    %Displays the upper-level (chapter) information---
-                                           % as determined above---in non-upper case in the header, to the right on even pages.
-\fancyhead[LO]{\rightmark}                 %Displays the lower-level (section) information---as
-                                           % determined above---in the header, to the left on odd pages.
-\renewcommand{\headrulewidth}{0.5pt}       %Underlines the header. (Set to 0pt if not required).
-\renewcommand{\footrulewidth}{0.5pt}       %Underlines the footer. (Set to 0pt if not required).
-
-%% Index
-\makeindex
-% Remove the index anchors from the HTML version to save size and bandwith.
-\newcommand{\ind}[1]{\begin{latexonly}\index{#1}\end{latexonly}}
-\newcommand{\makechapter}[2]{ \aname{#1}{} \chapter{\ahrefloc{#1}{#2}} \label{#1} }
-\newcommand{\makesection}[2]{ \aname{#1}{} \section{\ahrefloc{#1}{#2}} \label{#1} }
-\newcommand{\makesubsection}[2]{ \aname{#1}{} \subsection{\ahrefloc{#1}{#2}} \label{#1} }
-\newcommand{\makesubsubsection}[2]{ \aname{#1}{} \subsubsection{\ahrefloc{#1}{#2}} \label{#1} }
-\newcommand{\makeparagraph}[2]{ \aname{#1}{} \paragraph{\ahrefloc{#1}{#2}} \label{#1} }
-
-%% Images
-\newcommand{\logoscale}{0.7}
-\newcommand{\imgscale}{0.58}
-\newcommand{\insimg}[1]{\insscaleimg{\imgscale}{#1}}
-\newcommand{\insscaleimg}[2]{
-  \imgsrc{#2}{}
-  \begin{latexonly}
-    \scalebox{#1}{\includegraphics{#2}}
-  \end{latexonly}
-}
-
-%% 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}}
-\newcommand{\poption}[1]{{\bracehack\texttt{#1}}}
-\newcommand{\node}[1]{\texttt{#1}}
-\newcommand{\term}[1]{\texttt{#1}}
-\newcommand{\shell}[1]{\texttt{#1}}
-\newcommand{\ejabberd}{\texttt{ejabberd}}
-\newcommand{\Jabber}{Jabber}
-\newcommand{\XMPP}{XMPP}
-\newcommand{\esyntax}[1]{\begin{description}\titem{#1}\end{description}}
-
-%% Modules
-\newcommand{\module}[1]{\texttt{#1}}
-\newcommand{\modadhoc}{\module{mod\_adhoc}}
-\newcommand{\modannounce}{\module{mod\_announce}}
-\newcommand{\modclientstate}{\module{mod\_client\_state}}
-\newcommand{\modblocking}{\module{mod\_blocking}}
-\newcommand{\modcaps}{\module{mod\_caps}}
-\newcommand{\modcarboncopy}{\module{mod\_carboncopy}}
-\newcommand{\modconfigure}{\module{mod\_configure}}
-\newcommand{\moddisco}{\module{mod\_disco}}
-\newcommand{\modecho}{\module{mod\_echo}}
-\newcommand{\modfailban}{\module{mod\_fail2ban}}
-\newcommand{\modhttpbind}{\module{mod\_http\_bind}}
-\newcommand{\modhttpfileserver}{\module{mod\_http\_fileserver}}
-\newcommand{\modirc}{\module{mod\_irc}}
-\newcommand{\modlast}{\module{mod\_last}}
-\newcommand{\modmuc}{\module{mod\_muc}}
-\newcommand{\modmuclog}{\module{mod\_muc\_log}}
-\newcommand{\modoffline}{\module{mod\_offline}}
-\newcommand{\modping}{\module{mod\_ping}}
-\newcommand{\modprescounter}{\module{mod\_pres\_counter}}
-\newcommand{\modprivacy}{\module{mod\_privacy}}
-\newcommand{\modprivate}{\module{mod\_private}}
-\newcommand{\modproxy}{\module{mod\_proxy65}}
-\newcommand{\modpubsub}{\module{mod\_pubsub}}
-\newcommand{\modpubsubodbc}{\module{mod\_pubsub\_odbc}}
-\newcommand{\modregister}{\module{mod\_register}}
-\newcommand{\modregisterweb}{\module{mod\_register\_web}}
-\newcommand{\modroster}{\module{mod\_roster}}
-\newcommand{\modservicelog}{\module{mod\_service\_log}}
-\newcommand{\modsharedroster}{\module{mod\_shared\_roster}}
-\newcommand{\modsharedrosterldap}{\module{mod\_shared\_roster\_ldap}}
-\newcommand{\modsic}{\module{mod\_sic}}
-\newcommand{\modsip}{\module{mod\_sip}}
-\newcommand{\modstats}{\module{mod\_stats}}
-\newcommand{\modtime}{\module{mod\_time}}
-\newcommand{\modvcard}{\module{mod\_vcard}}
-\newcommand{\modvcardldap}{\module{mod\_vcard\_ldap}}
-\newcommand{\modvcardxupdate}{\module{mod\_vcard\_xupdate}}
-\newcommand{\modversion}{\module{mod\_version}}
-
-%% Contributed modules
-%\usepackage{ifthen}
-%\newboolean{modhttpbind}
-%\newcommand{\modhttpbind}{\module{mod\_http\_bind}}
-%\include{contributed_modules}
-%
-% Then in the document you can input the partial tex file with:
-%\ifthenelse{\boolean{modhttpbind}}{\input{mod_http_bind.tex}}{}
-
-%% Common options
-\newcommand{\iqdiscitem}[1]{\titem{iqdisc: Discipline} \ind{options!iqdisc}This specifies
-the processing discipline for #1 IQ queries (see section~\ref{modiqdiscoption}).}
-\newcommand{\hostitem}[1]{
-  \titem{host: HostName} \ind{options!host} This option defines the Jabber ID of the
-  service. If the \texttt{host} option is not specified, the Jabber ID will be the
-  hostname of the virtual host with the prefix `\jid{#1.}'. The keyword "@HOST@"
-  is replaced at start time with the real virtual host name.
-}
-\newcommand{\dbtype}{\titem{db\_type: internal|odbc} \ind{options!dbtype}
-  Define the type of storage where the module will create the tables and store user information.
-  The default is to store in the internal Mnesia database.
-  If \term{odbc} value is defined, make sure you have defined the database, see~\ref{database}.
-}
-
-%% Title page
-\include{version}
-\newlength{\larg}
-\setlength{\larg}{14.5cm}
-\title{
-{\rule{\larg}{1mm}}\vspace{7mm}
-\begin{tabular}{r}
-    {\huge {\bf ejabberd \version\ }} \\
-    \\
-    {\huge Installation and Operation Guide}
-\end{tabular}\\
-\vspace{2mm}
-{\rule{\larg}{1mm}}
-\begin{latexonly}
-\vspace{2mm} \\
-\vspace{5.5cm}
-\end{latexonly}
-}
-\begin{latexonly}
-\author{\begin{tabular}{p{13.7cm}}
-ejabberd Development Team
-\end{tabular}}
-\date{}
-\end{latexonly}
-
-
-%% Options
-\newcommand{\marking}[1]{#1} % Marking disabled
-\newcommand{\quoting}[2][yozhik]{} % Quotes disabled
-%\newcommand{\new}{\marginpar{\textsc{new}}} % Highlight new features
-%\newcommand{\improved}{\marginpar{\textsc{improved}}} % Highlight improved features
-
-%% To by-pass errors in the HTML version:
-\newstyle{.SPAN}{width:20\%; float:right; text-align:left; margin-left:auto;}
-\newstyle{H1.titlemain HR}{display:none;}
-\newstyle{TABLE.title}{border-top:1px solid grey;border-bottom:1px solid grey; background: \#efefef}
-\newstyle{H1.chapter A, H2.section A, H3.subsection A, H4.subsubsection A, H5.paragraph A}
-  {color:\#000000; text-decoration:none;}
-\newstyle{H1.chapter, H2.section, H3.subsection, H4.subsubsection, H5.paragraph}
-  {border-top: 1px solid grey; background: \#efefef; padding: 0.5ex}
-\newstyle{pre.verbatim}{margin:1ex 2ex;border:1px dashed lightgrey;background-color:\#f9f9f9;padding:0.5ex;}
-\newstyle{.dt-description}{margin:0ex 2ex;}
-\newstyle{table[border="1"]}{border-collapse:collapse;margin-bottom:1em;}
-\newstyle{table[border="1"] td}{border:1px solid \#aaa;padding:2px}
-% Don't display <hr> before and after tables or images:
-\newstyle{BLOCKQUOTE.table DIV.center DIV.center HR}{display:none;}
-\newstyle{BLOCKQUOTE.figure DIV.center DIV.center HR}{display:none;}
-
-%% 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{\txepref}[2]{\footahref{http://xmpp.org/extensions/xep-#1.html}{#2}}
-\newcommand{\xepref}[1]{\txepref{#1}{XEP-#1}}
-
-\begin{document}
-
-\label{titlepage}
-\begin{titlepage}
-  \maketitle{}
-
-%% Commenting. Breaking clean layout for now:
-%%  \begin{center}
-%%  {\insscaleimg{\logoscale}{logo.png}
-%%    \par
-%%  }
-%%  \end{center}
-
-%%  \begin{quotation}\textit{I can thoroughly recommend ejabberd for ease of setup ---
-%%  Kevin Smith, Current maintainer of the Psi project}\end{quotation}
-
-\end{titlepage}
-
-% 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}
-
-\label{toc}
-\tableofcontents{}
-
-% Input introduction.tex
-\input{introduction}
-
-\makechapter{installing}{Installing \ejabberd{}}
-
-\makesection{install.binary}{Installing \ejabberd{} with Binary Installer}
-
-Probably the easiest way to install an \ejabberd{} instant messaging server
-is using the binary installer published by ProcessOne.
-The binary installers of released \ejabberd{} versions
-are available in the ProcessOne \ejabberd{} downloads page:
-\ahrefurl{http://www.process-one.net/en/ejabberd/downloads}
-
-The installer will deploy and configure a full featured \ejabberd{}
-server and does not require any extra dependencies.
-
-In *nix systems, remember to set executable the binary installer before starting it. For example:
-\begin{verbatim}
-chmod +x ejabberd-2.0.0_1-linux-x86-installer.bin
-./ejabberd-2.0.0_1-linux-x86-installer.bin
-\end{verbatim}
-
-\ejabberd{} can be started manually at any time,
-or automatically by the operating system at system boot time.
-
-To start and stop \ejabberd{} manually,
-use the desktop shortcuts created by the installer.
-If the machine doesn't have a graphical system, use the scripts 'start'
-and 'stop' in the 'bin' directory where \ejabberd{} is installed.
-
-The Windows installer also adds ejabberd as a system service,
-and a shortcut to a debug console for experienced administrators.
-If you want ejabberd to be started automatically at boot time,
-go to the Windows service settings and set ejabberd to be automatically started.
-Note that the Windows service is a feature still in development,
-and for example it doesn't read the file ejabberdctl.cfg.
-
-On a *nix system, if you want ejabberd to be started as daemon at boot time,
-copy \term{ejabberd.init} from the 'bin' directory to something like \term{/etc/init.d/ejabberd}
-(depending on your distribution).
-Create a system user called \term{ejabberd},
-give it write access to the directories \term{database/} and \term{logs/}, and set that as home;
-the script will start the server with that user.
-Then you can call \term{/etc/inid.d/ejabberd start} as root to start the server.
-
-When ejabberd is started, the processes that are started in the system
-are \term{beam} or \term{beam.smp}, and also \term{epmd}.
-In Microsoft Windows, the processes are \term{erl.exe} and \term{epmd.exe}.
-For more information regarding \term{epmd} consult the section \ref{epmd}.
-
-If \term{ejabberd} doesn't start correctly in Windows,
-try to start it using the shortcut in desktop or start menu.
-If the window shows error 14001, the solution is to install:
-"Microsoft Visual C++ 2005 SP1 Redistributable Package".
-You can download it from
-\footahref{http://www.microsoft.com/}{www.microsoft.com}.
-Then uninstall \ejabberd{} and install it again.
-
-If \term{ejabberd} doesn't start correctly and a crash dump is generated,
-there was a severe problem.
-You can try starting \term{ejabberd} with
-the script \term{bin/live.bat} in Windows,
-or with the command \term{bin/ejabberdctl live} in other Operating Systems.
-This way you see the error message provided by Erlang
-and can identify what is exactly the problem.
-
-The \term{ejabberdctl} administration script is included in the \term{bin} directory.
-Please refer to the section~\ref{ejabberdctl} for details about \term{ejabberdctl},
-and configurable options to fine tune the Erlang runtime system.
-
-\makesection{install.os}{Installing \ejabberd{} with Operating System Specific Packages}
-
-Some Operating Systems provide a specific \ejabberd{} package adapted to
-the system architecture and libraries.
-It usually also checks dependencies
-and performs basic configuration tasks like creating the initial
-administrator account. Some examples are Debian and Gentoo. Consult the
-resources provided by your Operating System for more information.
-
-Usually those packages create a script like \term{/etc/init.d/ejabberd}
-to start and stop \ejabberd{} as a service at boot time.
-
-\makesection{install.cean}{Installing \ejabberd{} with CEAN}
-
-\footahref{http://cean.process-one.net/}{CEAN}
-(Comprehensive Erlang Archive Network) is a repository that hosts binary
-packages from many Erlang programs, including \ejabberd{} and all its dependencies.
-The binaries are available for many different system architectures, so this is an
-alternative to the binary installer and Operating System's \ejabberd{} packages.
-
-You will have to create your own \ejabberd{} start
-script depending of how you handle your CEAN installation.
-The default \term{ejabberdctl} script is located
-into \ejabberd{}'s priv directory and can be used as an example.
-
-\makesection{installation}{Installing \ejabberd{} from Source Code}
-\ind{install}
-
-The canonical form for distribution of \ejabberd{} stable releases is the source code package.
-Compiling \ejabberd{} from source code is quite easy in *nix systems,
-as long as your system have all the dependencies.
-
-\makesubsection{installreq}{Requirements}
-\ind{installation!requirements}
-
-To compile \ejabberd{} on a `Unix-like' operating system, you need:
-\begin{itemize}
-\item GNU Make
-\item GCC
-\item Libexpat 1.95 or higher
-\item Erlang/OTP R15B or higher.
-\item Libyaml 0.1.4 or higher
-\item OpenSSL 0.9.8 or higher, for STARTTLS, SASL and SSL encryption.
-\item Zlib 1.2.3 or higher, for Stream Compression support (\xepref{0138}). Optional.
-\item PAM library. Optional. For Pluggable Authentication Modules (PAM). See section \ref{pam}.
-\item GNU Iconv 1.8 or higher, for the IRC Transport (mod\_irc). Optional. Not needed on systems with GNU Libc. See section \ref{modirc}.
-\item ImageMagick's Convert program. Optional. For CAPTCHA challenges. See section \ref{captcha}.
-\end{itemize}
-
-\makesubsection{download}{Download Source Code}
-\ind{install!download}
-
-Released versions of \ejabberd{} are available in the ProcessOne \ejabberd{} downloads page:
-\ahrefurl{http://www.process-one.net/en/ejabberd/downloads}
-
-\ind{Git repository}
-Alternatively, the latest development source code can be retrieved from the Git repository using the commands:
-\begin{verbatim}
-git clone git://github.com/processone/ejabberd.git ejabberd
-cd ejabberd
-./autogen.sh
-\end{verbatim}
-
-
-\makesubsection{compile}{Compile}
-\ind{install!compile}
-
-To compile \ejabberd{} execute the commands:
-\begin{verbatim}
-./configure
-make
-\end{verbatim}
-
-The build configuration script allows several options.
-To get the full list run the command:
-\begin{verbatim}
-./configure --help
-\end{verbatim}
-
-Some options that you may be interested in modifying:
-\begin{description}
-	\titem{--prefix=/}
-	Specify the path prefix where the files will be copied when running
-	the \term{make install} command.
-
-	\titem{--enable-user[=USER]}
-	Allow this normal system user to execute the ejabberdctl script
-	(see section~\ref{ejabberdctl}),
-	read the configuration files,
-	read and write in the spool directory,
-	read and write in the log directory.
-	The account user and group must exist in the machine
-	before running \term{make install}.
-	This account doesn't need an explicit HOME directory, because
-	\term{/var/lib/ejabberd/} will be used by default.
-
-	\titem{--enable-pam}
-	Enable the PAM authentication method (see section \ref{pam}).
-
-	\titem{--enable-mssql}
-	Required if you want to use an external database.
-	See section~\ref{database} for more information.
-
-        \titem{--enable-tools}
-        Enable the use of development tools.
-
-        \titem{--enable-mysql}
-        Enable MySQL support (see section \ref{odbc}).
-
-        \titem{--enable-pgsql}
-        Enable PostgreSQL support (see section \ref{odbc}).
-
-        \titem{--enable-zlib}
-        Enable Stream Compression (XEP-0138) using zlib.
-
-        \titem{--enable-iconv}
-        Enable iconv support. This is needed for \term{mod\_irc} (see seciont \ref{modirc}).
-
-        \titem{--enable-debug}
-        Compile with \term{+debug\_info} enabled.
-
-	\titem{--enable-full-xml}
-	Enable the use of XML based optimisations.
-	It will for example use CDATA to escape characters in the XMPP stream.
-	Use this option only if you are sure your XMPP clients include a fully compliant XML parser.
-
-	\titem{--disable-transient-supervisors}
-	Disable the use of Erlang/OTP supervision for transient processes.
-
-	\titem{--enable-nif}
-        Replaces some critical Erlang functions with equivalents written in C to improve performance.
-\end{description}
-
-\makesubsection{install}{Install}
-\ind{install!install}
-
-To install \ejabberd{} in the destination directories, run the command:
-\begin{verbatim}
-make install
-\end{verbatim}
-Note that you probably need administrative privileges in the system
-to install \term{ejabberd}.
-
-The files and directories created are, by default:
-\begin{description}
-	\titem{/etc/ejabberd/} Configuration directory:
-		\begin{description}
-			\titem{ejabberd.yml} ejabberd configuration file
-			\titem{ejabberdctl.cfg} Configuration file of the administration script
-			\titem{inetrc} Network DNS configuration file
-		\end{description}
-	\titem{/lib/ejabberd/}
-		\begin{description}
-			\titem{ebin/} Erlang binary files (*.beam)
-			\titem{include/} Erlang header files (*.hrl)
-			\titem{priv/} Additional files required at runtime
-				\begin{description}
-					\titem{bin/} Executable programs
-					\titem{lib/} Binary system libraries (*.so)
-					\titem{msgs/} Translation files (*.msgs)
-				\end{description}
-		\end{description}
-	\titem{/sbin/ejabberdctl} Administration script (see section~\ref{ejabberdctl})
-	\titem{/share/doc/ejabberd/} Documentation of ejabberd
-	\titem{/var/lib/ejabberd/} Spool directory:
-		\begin{description}
-			\titem{.erlang.cookie} Erlang cookie file (see section \ref{cookie})
-			\titem{acl.DCD, ...} Mnesia database spool files (*.DCD, *.DCL, *.DAT)
-		\end{description}
-	\titem{/var/log/ejabberd/} Log directory (see section~\ref{logfiles}):
-		\begin{description}
-			\titem{ejabberd.log} ejabberd service log
-			\titem{erlang.log} Erlang/OTP system log
-		\end{description}
-\end{description}
-
-
-\makesubsection{start}{Start}
-\ind{install!start}
-
-You can use the \term{ejabberdctl} command line administration script to start and stop \ejabberd{}.
-If you provided the configure option \term{--enable-user=USER} (see \ref{compile}),
-you can execute \term{ejabberdctl} with either that system account or root.
-
-Usage example:
-\begin{verbatim}
-ejabberdctl start
-
-ejabberdctl status
-The node ejabberd@localhost is started with status: started
-ejabberd is running in that node
-
-ejabberdctl stop
-\end{verbatim}
-
-If \term{ejabberd} doesn't start correctly and a crash dump is generated,
-there was a severe problem.
-You can try starting \term{ejabberd} with
-the command \term{ejabberdctl live}
-to see the error message provided by Erlang
-and can identify what is exactly the problem.
-
-Please refer to the section~\ref{ejabberdctl} for details about \term{ejabberdctl},
-and configurable options to fine tune the Erlang runtime system.
-
-If you want ejabberd to be started as daemon at boot time,
-copy \term{ejabberd.init} to something like \term{/etc/init.d/ejabberd}
-(depending on your distribution).
-Create a system user called \term{ejabberd};
-it will be used by the script to start the server.
-Then you can call \term{/etc/inid.d/ejabberd start} as root to start the server.
-
-\makesubsection{bsd}{Specific Notes for BSD}
-\ind{install!bsd}
-
-The command to compile \ejabberd{} in BSD systems is:
-\begin{verbatim}
-gmake
-\end{verbatim}
-
-
-\makesubsection{solaris}{Specific Notes for Sun Solaris}
-\ind{install!solaris}
-
-You need to have \term{GNU install},
-but it isn't included in Solaris.
-It can be easily installed if your Solaris system
-is set up for \footahref{http://www.blastwave.org/}{blastwave.org}
-package repository.
-Make sure \term{/opt/csw/bin} is in your \term{PATH} and run:
-\begin{verbatim}
-pkg-get -i fileutils
-\end{verbatim}
-
-If that program is called \term{ginstall},
-modify the \ejabberd{} \term{Makefile} script to suit your system,
-for example:
-\begin{verbatim}
-cat Makefile | sed s/install/ginstall/ > Makefile.gi
-\end{verbatim}
-And finally install \ejabberd{} with:
-\begin{verbatim}
-gmake -f Makefile.gi ginstall
-\end{verbatim}
-
-
-\makesubsection{windows}{Specific Notes for Microsoft Windows}
-\ind{install!windows}
-
-\makesubsubsection{windowsreq}{Requirements}
-
-To compile \ejabberd{} on a Microsoft Windows system, you need:
-\begin{itemize}
-\item MS Visual C++ 6.0 Compiler
-\item \footahref{http://www.erlang.org/download.html}{Erlang/OTP R11B-5}
-\item \footahref{http://sourceforge.net/project/showfiles.php?group\_id=10127\&package\_id=11277}{Expat 2.0.0 or higher}
-\item
-\footahref{http://www.gnu.org/software/libiconv/}{GNU Iconv 1.9.2}
-(optional)
-\item \footahref{http://www.slproweb.com/products/Win32OpenSSL.html}{Shining Light OpenSSL 0.9.8d or higher}
-(to enable SSL connections)
-\item \footahref{http://www.zlib.net/}{Zlib 1.2.3 or higher}
-\end{itemize}
-
-
-\makesubsubsection{windowscom}{Compilation}
-
-We assume that we will try to put as much library as possible into \verb|C:\sdk\| to make it easier to track what is install for \ejabberd{}.
-
-\begin{enumerate}
-\item Install Erlang emulator (for example, into \verb|C:\sdk\erl5.5.5|).
-\item Install Expat library into \verb|C:\sdk\Expat-2.0.0|
-  directory.
-
-  Copy file \verb|C:\sdk\Expat-2.0.0\Libs\libexpat.dll|
-  to your Windows system directory (for example, \verb|C:\WINNT| or
-  \verb|C:\WINNT\System32|)
-\item Build and install the Iconv library into the directory
-  \verb|C:\sdk\GnuWin32|.
-
-  Copy file \verb|C:\sdk\GnuWin32\bin\lib*.dll| to your
-  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:\sdk\Expat-2.0.0\Libs| and
-  \verb|C:\sdk\GnuWin32\bin| to the \verb|PATH| environment
-  variable.
-\item Install OpenSSL in \verb|C:\sdk\OpenSSL| and add \verb|C:\sdk\OpenSSL\lib\VC| to your path or copy the binaries to your system directory.
-\item Install ZLib in \verb|C:\sdk\gnuWin32|. Copy
-  \verb|C:\sdk\GnuWin32\bin\zlib1.dll| to your system directory. If you change your path it should already be set after  libiconv install.
-\item Make sure the you can access Erlang binaries from your path. For example: \verb|set PATH=%PATH%;"C:\sdk\erl5.6.5\bin"|
-\item Depending on how you end up actually installing the library you might need to check and tweak the paths in the file configure.erl.
-\item While in the directory \verb|ejabberd\src| run:
-\begin{verbatim}
-configure.bat
-nmake -f Makefile.win32
-\end{verbatim}
-\item Edit the file \verb|ejabberd\src\ejabberd.yml| and run
-\begin{verbatim}
-werl -s ejabberd -name ejabberd
-\end{verbatim}
-\end{enumerate}
-
-%TODO: how to compile database support on windows?
-
-
-\makesection{initialadmin}{Create an XMPP Account for Administration}
-
-You need an XMPP account and grant him administrative privileges
-to enter the \ejabberd{} Web Admin:
-\begin{enumerate}
-\item Register an XMPP account on your \ejabberd{} server, for example \term{admin1@example.org}.
-  There are two ways to register an XMPP account:
-  \begin{enumerate}
-  \item Using \term{ejabberdctl}\ind{ejabberdctl} (see section~\ref{ejabberdctl}):
-\begin{verbatim}
-ejabberdctl register admin1 example.org FgT5bk3
-\end{verbatim}
-  \item Using an XMPP client and In-Band Registration (see section~\ref{modregister}).
-  \end{enumerate}
-\item Edit the \ejabberd{} configuration file to give administration rights to the XMPP account you created:
-\begin{verbatim}
-acl:
-  admin:
-    user:
-      - "admin1": "example.org"
-access:
-  configure:
-    admin: allow
-\end{verbatim}
-  You can grant administrative privileges to many XMPP accounts,
-  and also to accounts in other XMPP servers.
-\item Restart \ejabberd{} to load the new configuration.
-\item Open the Web Admin (\verb|http://server:port/admin/|) in your
-  favourite browser. Make sure to enter the \emph{full} JID as username (in this
-  example: \jid{admin1@example.org}. The reason that you also need to enter the
-  suffix, is because \ejabberd{}'s virtual hosting support.
-\end{enumerate}
-
-\makesection{upgrade}{Upgrading \ejabberd{}}
-
-To upgrade an ejabberd installation to a new version,
-simply uninstall the old version, and then install the new one.
-Of course, it is important that the configuration file
-and Mnesia database spool directory are not removed.
-
-\ejabberd{} automatically updates the Mnesia table definitions at startup when needed.
-If you also use an external database for storage of some modules,
-check if the release notes of the new ejabberd version
-indicates you need to also update those tables.
-
-
-\makechapter{configure}{Configuring \ejabberd{}}
-\ind{configuration file}
-
-\makesection{basicconfig}{Basic Configuration}
-
-The configuration file will be loaded the first time you start \ejabberd{}.
-The configuration file name MUST have ``.yml'' extension. This helps ejabberd
-to differentiate between the new and legacy file formats (see section~\ref{oldconfig}).
-
-Note that \ejabberd{} never edits the configuration file.
-
-The configuration file is written in
-\footahref{http://en.wikipedia.org/wiki/YAML}{YAML}.
-However, different scalars are treated as different types:
-\begin{itemize}
-\item unquoted or single-quoted strings. The type is called \verb|atom()|
-  in this document.
-  Examples: \verb|dog|, \verb|'Jupiter'|, \verb|'3.14159'|, \verb|YELLOW|.
-\item numeric literals. The type is called \verb|integer()|, \verb|float()| or,
-  if both are allowed, \verb|number()|.
-  Examples: \verb|3|, \verb|-45.0|, \verb|.0|
-\item double-quoted or folded strings. The type is called \verb|string()|.
-  Examples of a double-quoted string:
-  \verb|"Lizzard"|, \verb|"orange"|, \verb|"3.14159"|.
-  Examples of a folded string:
-\begin{verbatim}
-> Art thou not Romeo,
-  and a Montague?
-\end{verbatim}
-\begin{verbatim}
-| Neither, fair saint,
-  if either thee dislike.
-\end{verbatim}
-For associative arrays ("mappings") and lists you can use both outline
-indentation and compact syntax (aka ``JSON style''). For example, the following is equivalent:
-\begin{verbatim}
-{param1: ["val1", "val2"], param2: ["val3", "val4"]}
-\end{verbatim}
-and
-\begin{verbatim}
-param1:
-  - "val1"
-  - "val2"
-param2:
-  - "val3"
-  - "val4"
-\end{verbatim}
-Note that both styles are used in this document.
-\end{itemize}
-
-\makesubsection{oldconfig}{Legacy Configuration File}
-In previous \ejabberd{} version the configuration file should be written
-in Erlang terms. The format is still supported, but it is highly recommended
-to convert it to the new YAML format using \term{convert\_to\_yaml} command
-from \term{ejabberdctl} (see~\ref{ejabberdctl} and \ref{list-eja-commands} for details).
-
-If you want to specify some options using the old Erlang format,
-you can set them in an additional cfg file, and include it using
-the \option{include\_config\_file} option, see \ref{includeconfigfile}
-for the option description and a related example in \ref{accesscommands}.
-
-If you just want to provide an erlang term inside an option,
-you can use the \term{"> erlangterm."} syntax for embedding erlang terms in a YAML file, for example:
-\begin{verbatim}
-modules:
-  mod_cron:
-    tasks:
-      - time: 10
-        units: seconds
-        module: mnesia
-        function: info
-        arguments: "> []."
-      - time: 3
-        units: seconds
-        module: ejabberd_auth
-        function: try_register
-        arguments: "> [\"user1\", \"localhost\", \"pass\"]."
-\end{verbatim}
-
-\makesubsection{hostnames}{Host Names}
-\ind{options!hosts}\ind{host names}
-
-The option \option{hosts} defines a list containing one or more domains that
-\ejabberd{} will serve.
-
-The syntax is:
-\esyntax{[HostName]}
-
-Examples:
-\begin{itemize}
-\item Serving one domain:
-\begin{verbatim}
-hosts: ["example.org"]
-\end{verbatim}
-\item Serving three domains:
-\begin{verbatim}
-hosts:
-  - "example.net"
-  - "example.com"
-  - "jabber.somesite.org"
-\end{verbatim}
-\end{itemize}
-
-\makesubsection{virtualhost}{Virtual Hosting}
-\ind{virtual hosting}\ind{virtual hosts}\ind{virtual domains}
-
-Options can be defined separately for every virtual host using the
-\term{host\_config} option.
-
-The syntax is: \ind{options!host\_config}
-\esyntax{\{HostName: [Option, ...]\}}
-
-Examples:
-\begin{itemize}
-\item Domain \jid{example.net} is using the internal authentication method while
-  domain \jid{example.com} is using the \ind{LDAP}LDAP server running on the
-  domain \jid{localhost} to perform authentication:
-\begin{verbatim}
-host_config:
-  "example.net"
-    auth_method: internal
-  "example.com":
-    auth_method: ldap
-    ldap_servers:
-      - "localhost"
-    ldap_uids:
-      - "uid"
-    ldap_rootdn: "dc=localdomain"
-    ldap_rootdn: "dc=example,dc=com"
-    ldap_password: ""
-\end{verbatim}
-\item Domain \jid{example.net} is using \ind{odbc}ODBC to perform authentication
-  while domain \jid{example.com} is using the LDAP servers running on the domains
-  \jid{localhost} and \jid{otherhost}:
-\begin{verbatim}
-host_config:
-  "example.net":
-    auth_method: odbc
-    odbc_type: odbc
-    odbc_server: "DSN=ejabberd;UID=ejabberd;PWD=ejabberd"
-  "example.com":
-    auth_method: ldap
-    ldap_servers:
-      - "localhost"
-      - "otherhost"
-    ldap_uids:
-      - "uid"
-    ldap_rootdn: "dc=localdomain"
-    ldap_rootdn: "dc=example,dc=com"
-    ldap_password: ""
-\end{verbatim}
-\end{itemize}
-
-To define specific ejabberd modules in a virtual host,
-you can define the global \term{modules} option with the common modules,
-and later add specific modules to certain virtual hosts.
-To accomplish that, instead of defining each option in \term{host\_config}
-use \term{append\_host\_config} with the same syntax.
-
-In this example three virtual hosts have some similar modules, but there are also
-other different modules for some specific virtual hosts:
-\begin{verbatim}
-## This ejabberd server has three vhosts:
-hosts:
-  - "one.example.org"
-  - "two.example.org"
-  - "three.example.org"
-
-## Configuration of modules that are common to all vhosts
-modules:
-  mod_roster:    {}
-  mod_configure: {}
-  mod_disco:     {}
-  mod_private:   {}
-  mod_time:      {}
-  mod_last:      {}
-  mod_version:   {}
-
-## Add some modules to vhost one:
-append_host_config:
-  "one.example.org":
-    modules:
-      mod_echo:
-        host: "echo-service.one.example.org"
-      mod_http_bind: {}
-      mod_logxml: {}
-
-## Add a module just to vhost two:
-append_host_config:
-  "two.example.org":
-    modules:
-      mod_echo:
-        host: "mirror.two.example.org"
-\end{verbatim}
-
-\makesubsection{listened}{Listening Ports}
-\ind{options!listen}
-
-The option \option{listen} defines for which ports, addresses and network protocols \ejabberd{}
-will listen and what services will be run on them. Each element of the list is an
-associative array with the following elements:
-\begin{itemize}
-\item Port number. Optionally also the IP address and/or a transport protocol.
-\item Listening module that serves this port.
-\item Options for the TCP socket and for the listening module.
-\end{itemize}
-
-The option syntax is:
-\esyntax{[Listener, ...]}
-Example:
-\begin{verbatim}
-listen:
-  -
-    port: 5222
-    module: ejabberd_c2s
-    starttls: true
-    certfile: "/path/to/certfile.pem"
-  -
-    port: 5269
-    module: ejabberd_s2s_in
-    transport: tcp
-\end{verbatim}
-
-\makesubsubsection{listened-port}{Port Number, IP Address and Transport Protocol}
-
-The port number defines which port to listen for incoming connections.
-It can be a Jabber/XMPP standard port 
-(see section \ref{firewall}) or any other valid port number.
-
-The IP address can be represented as a string.
-The socket will listen only in that network interface.
-It is possible to specify a generic address,
-so \ejabberd{} will listen in all addresses.
-Depending in the type of the IP address, IPv4 or IPv6 will be used.
-When not specified the IP address, it will listen on all IPv4 network addresses.
-
-Some example values for IP address:
-\begin{itemize}
-\item \verb|"0.0.0.0"| to listen in all IPv4 network interfaces. This is the default value when no IP is specified.
-\item \verb|"::"| to listen in all IPv6 network interfaces
-\item \verb|"10.11.12.13"| is the IPv4 address \verb|10.11.12.13|
-\item \verb|"::FFFF:127.0.0.1"| is the IPv6 address \verb|::FFFF:127.0.0.1/128|
-\end{itemize}
-
-The transport protocol can be \term{tcp} or \term{udp}.
-Default is \term{tcp}.
-
-
-\makesubsubsection{listened-module}{Listening Module}
-
-\ind{modules!ejabberd\_c2s}\ind{modules!ejabberd\_s2s\_in}\ind{modules!ejabberd\_service}\ind{modules!ejabberd\_http}\ind{protocols!XEP-0114: Jabber Component Protocol}
-The available modules, their purpose and the options allowed by each one are:
-\begin{description}
-  \titem{\texttt{ejabberd\_c2s}}
-    Handles c2s connections.\\
-    Options: \texttt{access}, \texttt{certfile}, \texttt{ciphers}, \texttt{protocol\_options}
-    \texttt{max\_ack\_queue}, \texttt{max\_fsm\_queue},
-    \texttt{max\_stanza\_size}, \texttt{resend\_on\_timeout},
-    \texttt{resume\_timeout}, \texttt{shaper},
-    \texttt{starttls}, \texttt{starttls\_required},
-    \texttt{stream\_management}, \texttt{tls},
-    \texttt{zlib}, \texttt{tls\_compression}
-  \titem{\texttt{ejabberd\_s2s\_in}}
-    Handles incoming s2s connections.\\
-    Options: \texttt{max\_stanza\_size}, \texttt{shaper}, \texttt{tls\_compression}
-  \titem{\texttt{ejabberd\_service}}
-    Interacts with an \footahref{http://www.ejabberd.im/tutorials-transports}{external component}
-    (as defined in the Jabber Component Protocol (\xepref{0114}).\\
-    Options: \texttt{access}, \texttt{hosts}, \texttt{max\_fsm\_queue},
-    \texttt{service\_check\_from}, \texttt{shaper\_rule}
-  \titem{\texttt{ejabberd\_sip}}
-    Handles SIP requests as defined in
-    \footahref{http://tools.ietf.org/html/rfc3261}{RFC 3261}.\\
-    Options: \texttt{certfile}, \texttt{tls}
-  \titem{\texttt{ejabberd\_stun}}
-    Handles STUN/TURN requests as defined in
-    \footahref{http://tools.ietf.org/html/rfc5389}{RFC 5389} and
-    \footahref{http://tools.ietf.org/html/rfc5766}{RFC 5766}.\\
-    Options: \texttt{certfile}, \texttt{tls}, \texttt{use\_turn}, \texttt{turn\_ip},
-    \texttt{turn\_port\_range}, \texttt{turn\_max\_allocations},
-    \texttt{turn\_max\_permissions}, \texttt{shaper}, \texttt{server\_name},
-    \texttt{auth\_realm}, \texttt{auth\_type}
-  \titem{\texttt{ejabberd\_http}}
-    Handles incoming HTTP connections.\\
-    Options: \texttt{captcha}, \texttt{certfile}, \texttt{default\_host}, \texttt{http\_bind}, \texttt{http\_poll},
-    \texttt{request\_handlers}, \texttt{tls}, \texttt{tls\_compression}, \texttt{trusted\_proxies}, \texttt{web\_admin}\\
-  \titem{\texttt{ejabberd\_xmlrpc}}
-    Handles XML-RPC requests to execute ejabberd commands (\ref{eja-commands}).\\
-    Options: \texttt{access\_commands}, \texttt{maxsessions}, \texttt{timeout}.\\
-    You can find option explanations, example configuration in old and new format,
-    and example calls in several languages in the old
-    \footahref{http://www.ejabberd.im/ejabberd\_xmlrpc}{ejabberd\_xmlrpc documentation}.
-\end{description}
-
-
-\makesubsubsection{listened-options}{Options}
-
-This is a detailed description of each option allowed by the listening modules:
-\begin{description}
-  \titem{access: AccessName} \ind{options!access}This option defines
-    access to the port. The default value is \term{all}.
-  \titem{backlog: Value} \ind{options!backlog}The backlog value
-    defines the maximum length that the queue of pending connections may
-    grow to. This should be increased if the server is going to handle
-    lots of new incoming connections as they may be dropped if there is
-    no space in the queue (and ejabberd was not able to accept them
-    immediately). Default value is 5.
-  \titem{captcha: true|false} \ind{options!http-captcha}
-    Simple web page that allows a user to fill a CAPTCHA challenge (see section \ref{captcha}).
-  \titem{certfile: Path} Full path to a file containing the default SSL certificate.
-    To define a certificate file specific for a given domain, use the global option \term{domain\_certfile}.
-  \titem{ciphers: Ciphers} OpenSSL ciphers list in the same format accepted by
-  `\verb|openssl ciphers|' command.
-  \titem{protocol\_options: ProtocolOpts} \ind{options!protocol\_options}
-  List of general options relating to SSL/TLS. These map to
-  \footahref{https://www.openssl.org/docs/ssl/SSL\_CTX\_set\_options.html}{OpenSSL's set\_options()}.
-  For a full list of options available in ejabberd,
-  \footahref{https://github.com/processone/tls/blob/master/c\_src/options.h}{see the source}.
-  The default entry is: \verb|"no_sslv2"|
-  \titem{default\_host: undefined|HostName\}}
-    If the HTTP request received by ejabberd contains the HTTP header \term{Host}
-    with an ambiguous virtual host that doesn't match any one defined in ejabberd (see \ref{hostnames}),
-    then this configured HostName is set as the request Host.
-    The default value of this option is: \term{undefined}.
-  \titem{hosts: \{Hostname: [HostOption, ...]\}}\ind{options!hosts}
-    The external Jabber component that connects to this \term{ejabberd\_service}
-    can serve one or more hostnames.
-    As \term{HostOption} you can define options for the component;
-    currently the only allowed option is the password required to the component
-    when attempt to connect to ejabberd: \poption{password: Secret}.
-    Note that you cannot define in a single \term{ejabberd\_service} components of
-    different services: add an \term{ejabberd\_service} for each service,
-    as seen in an example below.
-  \titem{http\_bind: true|false} \ind{options!http\_bind}\ind{protocols!XEP-0206: HTTP Binding}\ind{JWChat}\ind{web-based XMPP client}
-    This option enables HTTP Binding (\xepref{0124} and \xepref{0206}) support. HTTP Bind
-    enables access via HTTP requests to \ejabberd{} from behind firewalls which
-    do not allow outgoing sockets on port 5222.
-
-    Remember that you must also install and enable the module mod\_http\_bind.
-
-    If HTTP Bind is enabled, it will be available at
-    \verb|http://server:port/http-bind/|. Be aware that support for HTTP Bind
-    is also needed in the \XMPP{} client. Remark also that HTTP Bind can be
-    interesting to host a web-based \XMPP{} client such as
-    \footahref{http://jwchat.sourceforge.net/}{JWChat}
-    (check the tutorials to install JWChat with ejabberd and an
-    \footahref{http://www.ejabberd.im/jwchat-localserver}{embedded local web server}
-    or \footahref{http://www.ejabberd.im/jwchat-apache}{Apache}).
-  \titem{http\_poll: true|false} \ind{options!http\_poll}\ind{protocols!XEP-0025: HTTP Polling}\ind{JWChat}\ind{web-based XMPP client}
-    This option enables HTTP Polling (\xepref{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 \XMPP{} client. Remark also that HTTP Polling can be
-    interesting to host a web-based \XMPP{} client such as
-    \footahref{http://jwchat.sourceforge.net/}{JWChat}.
-
-    The maximum period of time to keep a client session active without
-    an incoming POST request can be configured with the global option
-    \term{http\_poll\_timeout}. The default value is five minutes.
-    The option can be defined in \term{ejabberd.yml}, expressing the time
-    in seconds: \verb|{http_poll_timeout, 300}.|
-  \titem{max\_ack\_queue: Size}
-    This option specifies the maximum number of unacknowledged stanzas
-    queued for possible retransmission if \term{stream\_management} is
-    enabled. When the limit is exceeded, the client session is
-    terminated. This option can be specified for \term{ejabberd\_c2s}
-    listeners. The allowed values are positive integers and
-    \term{infinity}. Default value: \term{500}.
-  \titem{max\_fsm\_queue: Size}
-    This option specifies the maximum number of elements in the queue of the FSM
-    (Finite State Machine).
-    Roughly speaking, each message in such queues represents one XML
-    stanza queued to be sent into its relevant outgoing stream. If queue size
-    reaches the limit (because, for example, the receiver of stanzas is too slow),
-    the FSM and the corresponding connection (if any) will be terminated
-    and error message will be logged.
-    The reasonable value for this option depends on your hardware configuration.
-    However, there is no much sense to set the size above 1000 elements.
-    This option can be specified for \term{ejabberd\_service} and
-    \term{ejabberd\_c2s} listeners,
-    or also globally for \term{ejabberd\_s2s\_out}.
-    If the option is not specified for \term{ejabberd\_service} or
-    \term{ejabberd\_c2s} listeners,
-    the globally configured value is used.
-    The allowed values are integers and 'undefined'.
-    Default value: 'undefined'.
-  \titem{max\_stanza\_size: Size}
-    \ind{options!max\_stanza\_size}This option specifies an
-    approximate maximum size in bytes of XML stanzas.  Approximate,
-    because it is calculated with the precision of one block of read
-    data. For example \verb|{max_stanza_size, 65536}|.  The default
-    value is \term{infinity}. Recommended values are 65536 for c2s
-    connections and 131072 for s2s connections. s2s max stanza size
-    must always much higher than c2s limit. Change this value with
-    extreme care as it can cause unwanted disconnect if set too low.
-  \titem{request\_handlers: \{Path: Module\}} To define one or several handlers that will serve HTTP requests.
-    The Path is a string; so the URIs that start with that Path will be served by Module.
-    For example, if you want \term{mod\_foo} to serve the URIs that start with \term{/a/b/},
-    and you also want \term{mod\_http\_bind} to serve the URIs \term{/http-bind/},
-    use this option:
-\begin{verbatim}
-request_handlers:
-  /"a"/"b": mod_foo
-  /"http-bind": mod_http_bind
-\end{verbatim}
-  \titem{resend\_on\_timeout: true|false|if\_offline}
-    If \term{stream\_management} is enabled and this option is set to
-    \term{true}, any stanzas that weren't acknowledged by the client
-    will be resent on session timeout. This behavior might often be
-    desired, but could have unexpected results under certain
-    circumstances. For example, a message that was sent to two resources
-    might get resent to one of them if the other one timed out.
-    Therefore, the default value for this option is \term{false}, which
-    tells ejabberd to generate an error message instead. As an
-    alternative, the option may be set to \term{if\_offline}. In this
-    case, unacknowledged stanzas are resent only if no other resource is
-    online when the session times out. Otherwise, error messages are
-    generated. The option can be specified for \term{ejabberd\_c2s}
-    listeners.
-  \titem{resume\_timeout: Seconds}
-    This option configures the number of seconds until a session times
-    out if the connection is lost. During this period of time, a client
-    may resume the session if \term{stream\_management} is enabled. This
-    option can be specified for \term{ejabberd\_c2s} listeners. Setting
-    it to \term{0} effectively disables session resumption. The default
-    value is \term{300}.
-  \titem{service\_check\_from: true|false}
-    \ind{options!service\_check\_from}
-    This option can be used with \term{ejabberd\_service} only.
-    \xepref{0114} requires that the domain must match the hostname of the component.
-    If this option is set to \term{false}, \ejabberd{} will allow the component
-    to send stanzas with any arbitrary domain in the 'from' attribute.
-    Only use this option if you are completely sure about it.
-    The default value is \term{true}, to be compliant with \xepref{0114}.
-  \titem{shaper: none|ShaperName} \ind{options!shaper}This option defines a
-    shaper for the port (see section~\ref{shapers}). The default value
-    is \term{none}.
-  \titem{shaper\_rule: none|ShaperRule} \ind{options!shaperrule}This option defines a
-    shaper rule for the \term{ejabberd\_service} (see section~\ref{shapers}). The recommended value
-    is \term{fast}.
-  \titem{starttls: true|false} \ind{options!starttls}\ind{STARTTLS}This option
-    specifies that STARTTLS encryption is available on connections to the port.
-    You should also set the \option{certfile} option.
-    You can define a certificate file for a specific domain using the global option \option{domain\_certfile}.
-  \titem{starttls\_required: true|false} \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.
-    You can define a certificate file for a specific domain using the global option \option{domain\_certfile}.
-  \titem{stream\_management: true|false}
-    Setting this option to \term{false} disables ejabberd's support for
-    Stream Management (\xepref{0198}). It can be specified for
-    \term{ejabberd\_c2s} listeners. The default value is \term{true}.
-  \titem{timeout: Integer} \ind{options!timeout}
-    Timeout of the connections, expressed in milliseconds.
-    Default: 5000
-  \titem{tls: true|false} \ind{options!tls}\ind{TLS}This option specifies that traffic on
-    the port will be encrypted using SSL immediately after connecting.
-    This was the traditional encryption method in the early Jabber software,
-    commonly on port 5223 for client-to-server communications.
-    But this method is nowadays deprecated and not recommended.
-    The preferable encryption method is STARTTLS on port 5222, as defined 
-    \footahref{http://xmpp.org/rfcs/rfc6120.html\#tls}{RFC 6120: XMPP Core},
-    which can be enabled in \ejabberd{} with the option \term{starttls}.
-    If this option is set, you should also set the \option{certfile} option.
-    The option \term{tls} can also be used in \term{ejabberd\_http} to support HTTPS.
-  \titem{tls\_compression: true|false}
-  Whether to enable or disable TLS compression. The default value is \term{true}.
-  \titem{trusted\_proxies: all | [IpString]} \ind{options!trusted\_proxies}
-    Specify what proxies are trusted when an HTTP request contains the header \term{X-Forwarded-For}
-    You can specify \term{all} to allow all proxies, or specify a list of IPs in string format.
-    The default value is: \term{["127.0.0.1"]}
-  \titem{web\_admin: true|false} \ind{options!web\_admin}\ind{web admin}This option
-    enables the Web Admin 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.
-  \titem{zlib: true|false} \ind{options!zlib}\ind{protocols!XEP-0138: Stream Compression}\ind{Zlib}This
-    option specifies that Zlib stream compression (as defined in \xepref{0138})
-    is available on connections to the port.
-\end{description}
-
-There are some additional global options that can be specified in the ejabberd configuration file (outside \term{listen}):
-\begin{description}
-  \titem{s2s\_use\_starttls: false|optional|required|required\_trusted}
-  \ind{options!s2s\_use\_starttls}\ind{STARTTLS}This option defines if 
-  s2s connections don't use STARTTLS encryption; if STARTTLS can be used optionally;
-  if STARTTLS is required to establish the connection;
-  or if STARTTLS is required and the remote certificate must be valid and trusted.
-  The default value is to not use STARTTLS: \term{false}.
-  \titem{s2s\_certfile: Path} \ind{options!s2s\_certificate}Full path to a
-  file containing a SSL certificate.
-  \titem{domain\_certfile: Path} \ind{options!domain\_certfile}
-  Full path to the file containing the SSL certificate for a specific domain.
-  \titem{s2s\_ciphers: Ciphers} \ind{options!s2s\_ciphers} OpenSSL ciphers list
-  in the same format accepted by `\verb|openssl ciphers|' command.
-  \titem{s2s\_protocol\_options: ProtocolOpts} \ind{options!s2s\_protocol\_options}
-  List of general options relating to SSL/TLS. These map to
-  \footahref{https://www.openssl.org/docs/ssl/SSL\_CTX\_set\_options.html}{OpenSSL's set\_options()}.
-  For a full list of options available in ejabberd,
-  \footahref{https://github.com/processone/tls/blob/master/c\_src/options.h}{see the source}.
-  The default entry is: \verb|"no_sslv2"|
-  \titem{outgoing\_s2s\_families: [Family, ...]} \ind{options!outgoing\_s2s\_families}
-  Specify which address families to try, in what order.
-  By default it first tries connecting with IPv4, if that fails it tries using IPv6.
-  \titem{outgoing\_s2s\_timeout: Timeout} \ind{options!outgoing\_s2s\_timeout}
-  The timeout in milliseconds for outgoing S2S connection attempts.
-  \titem{s2s\_dns\_timeout: Timeout} \ind{options!s2s\_dns\_timeout}
-  The timeout in seconds for DNS resolving. The default value is \term{10}.
-  \titem{s2s\_dns\_retries: Number} \ind{options!s2s\_dns\_retries}
-  DNS resolving retries in seconds. The default value is \term{2}.
-  \titem{s2s\_policy: Access} \ind{options!s2s\_policy}
-  The policy for incoming and outgoing s2s connections to other XMPP servers.
-  The default value is \term{all}.
-  \titem{s2s\_max\_retry\_delay: Seconds} \ind{options!s2s\_max\_retry\_delay}
-  The maximum allowed delay for retry to connect after a failed connection attempt.
-  Specified in seconds. The default value is 300 seconds (5 minutes).
-  \titem{s2s\_tls\_compression: true|false}
-  Whether to enable or disable TLS compression for s2s connections.
-  The default value is \term{true}.
-  \titem{max\_fsm\_queue: Size}
-    This option specifies the maximum number of elements in the queue of the FSM
-    (Finite State Machine).
-    Roughly speaking, each message in such queues represents one XML
-    stanza queued to be sent into its relevant outgoing stream. If queue size
-    reaches the limit (because, for example, the receiver of stanzas is too slow),
-    the FSM and the corresponding connection (if any) will be terminated
-    and error message will be logged.
-    The reasonable value for this option depends on your hardware configuration.
-    However, there is no much sense to set the size above 1000 elements.
-    This option can be specified for \term{ejabberd\_service} and
-    \term{ejabberd\_c2s} listeners,
-    or also globally for \term{ejabberd\_s2s\_out}.
-    If the option is not specified for \term{ejabberd\_service} or
-    \term{ejabberd\_c2s} listeners,
-    the globally configured value is used.
-    The allowed values are integers and 'undefined'.
-    Default value: 'undefined'.
-  \titem{route\_subdomains: local|s2s}
-  Defines if ejabberd must route stanzas directed to subdomains locally (compliant with 
-  \footahref{http://xmpp.org/rfcs/rfc6120.html\#rules-local}{RFC 6120 Local Domain rules}),
-  or to foreign server using S2S (compliant with
-  \footahref{http://xmpp.org/rfcs/rfc6120.html\#rules-remote}{RFC 6120 Remote Domain rules}).
-\end{description}
-
-\makesubsubsection{listened-examples}{Examples}
-
-For example, the following simple configuration defines:
-\begin{itemize}
-\item There are three domains. The default certificate file is \term{server.pem}.
-However, the c2s and s2s connections to the domain \term{example.com} use the file \term{example\_com.pem}.
-\item Port 5222 listens for c2s connections with STARTTLS,
-  and also allows plain connections for old clients.
-\item Port 5223 listens for c2s connections with the old SSL.
-\item Port 5269 listens for s2s connections with STARTTLS. The socket is set for IPv6 instead of IPv4.
-\item Port 3478 listens for STUN requests over UDP.
-\item Port 5280 listens for HTTP requests, and serves the HTTP Poll service.
-\item Port 5281 listens for HTTP requests, using HTTPS to serve HTTP-Bind (BOSH) and the Web Admin as explained in
-  section~\ref{webadmin}. The socket only listens connections to the IP address 127.0.0.1.
-\end{itemize}
-\begin{verbatim}
-hosts:
-  - "example.com"
-  - "example.org"
-  - "example.net"
-
-listen:
-  - 
-    port: 5222
-    module: ejabberd_c2s
-    access: c2s
-    shaper: c2s_shaper
-    starttls: true
-    certfile: "/etc/ejabberd/server.pem"
-    max_stanza_size: 65536
-  - 
-    port: 5223
-    module: ejabberd_c2s
-    access: c2s
-    shaper: c2s_shaper
-    tls: true
-    certfile: "/etc/ejabberd/server.pem"
-    max_stanza_size: 65536
-  - 
-    port: 5269
-    ip: "::"
-    module: ejabberd_s2s_in
-    shaper: s2s_shaper
-    max_stanza_size: 131072
-  - 
-    port: 3478
-    transport: udp
-    module: ejabberd_stun
-  - 
-    port: 5280
-    module: ejabberd_http
-    http_poll: true
-  - 
-    port: 5281
-    ip: "127.0.0.1"
-    module: ejabberd_http
-    web_admin: true
-    http_bind: true
-    tls: true
-    certfile: "/etc/ejabberd/server.pem"
-
-s2s_use_starttls: optional
-s2s_certfile: "/etc/ejabberd/server.pem"
-host_config:
-  "example.com":
-    domain_certfile: "/etc/ejabberd/example_com.pem"
-outgoing_s2s_families:
-  - ipv4
-  - ipv6
-outgoing_s2s_timeout: 10000
-\end{verbatim}
-
-In this example, the following configuration defines that:
-\begin{itemize}
-\item c2s connections are listened for on port 5222 (all IPv4 addresses) and
-  on port 5223 (SSL, IP 192.168.0.1 and fdca:8ab6:a243:75ef::1) and denied
-  for the user called `\term{bad}'.
-\item s2s connections are listened for on port 5269 (all IPv4 addresses) 
-  with STARTTLS for secured traffic strictly required, and the certificates are verified. 
-  Incoming and outgoing connections of remote XMPP servers are denied,
-  only two servers can connect: "jabber.example.org" and "example.com".
-\item Port 5280 is serving the Web Admin and the HTTP Polling service
-  in all the IPv4 addresses. Note
-  that it is also possible to serve them on different ports. The second
-  example in section~\ref{webadmin} 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://www.ejabberd.im/pyaimt}{AIM transport}
-  \jid{aim.example.org} is connected to port 5233 on localhost IP addresses
-  (127.0.0.1 and ::1) 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://www.ejabberd.im/pymsnt}{MSN transport}
-  \jid{msn.example.org} is connected to port 5235 with password
-  `\term{msnsecret}'.
-\item \ind{transports!Yahoo}The
-  \footahref{http://www.ejabberd.im/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://www.ejabberd.im/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://www.ejabberd.im/jmc}{Jabber Mail Component}
-  \jid{jmc.example.org} is connected to port 5238 with password
-  `\term{jmcsecret}'.
-\item The service custom has enabled the special option to avoiding checking the \term{from} attribute in the packets send by this component. The component can send packets in behalf of any users from the server, or even on behalf of any server.
-\end{itemize}
-\begin{verbatim}
-acl: 
-  blocked: 
-    user: "bad"
-  trusted_servers: 
-    server:
-      - "example.com"
-      - "jabber.example.org"
-  xmlrpc_bot: 
-    user: 
-      - "xmlrpc-robot": "example.org"
-shaper: 
-  normal: 1000
-access: 
-  c2s: 
-    blocked: deny
-    all: allow
-  c2s_shaper: 
-    admin: none
-    all: normal
-  xmlrpc_access: 
-    xmlrpc_bot: allow
-  s2s:
-    trusted_servers: allow
-    all: deny
-s2s_certfile: "/path/to/ssl.pem"
-s2s_access: s2s
-s2s_use_starttls: required_trusted
-listen: 
-  - 
-    port: 5222
-    module: ejabberd_c2s
-    shaper: c2s_shaper
-    access: c2s
-  - 
-    ip: "192.168.0.1"
-    port: 5223
-    module: ejabberd_c2s
-    certfile: "/path/to/ssl.pem"
-    tls: true
-    access: c2s
-  - 
-    ip: "FDCA:8AB6:A243:75EF::1"
-    port: 5223
-    module: ejabberd_c2s
-    certfile: "/path/to/ssl.pem"
-    tls: true
-    access: c2s
-  - 
-    port: 5269
-    module: ejabberd_s2s_in
-  - 
-    port: 5280
-    module: ejabberd_http
-    web_admin: true
-    http_poll: true
-  - 
-    port: 4560
-    module: ejabberd_xmlrpc
-  - 
-    ip: "127.0.0.1"
-    port: 5233
-    module: ejabberd_service
-    hosts: 
-      "aim.example.org": 
-        password: "aimsecret"
-  - 
-    ip: "::1"
-    port: 5233
-    module: ejabberd_service
-    hosts: 
-      "aim.example.org": 
-        password: "aimsecret"
-  - 
-    port: 5234
-    module: ejabberd_service
-    hosts: 
-      "icq.example.org": 
-        password: "jitsecret"
-      "sms.example.org": 
-        password: "jitsecret"
-  - 
-    port: 5235
-    module: ejabberd_service
-    hosts: 
-      "msn.example.org": 
-        password: "msnsecret"
-  - 
-    port: 5236
-    module: ejabberd_service
-    hosts: 
-      "yahoo.example.org": 
-        password: "yahoosecret"
-  - 
-    port: 5237
-    module: ejabberd_service
-    hosts: 
-      "gg.example.org": 
-        password: "ggsecret"
-  - 
-    port: 5238
-    module: ejabberd_service
-    hosts: 
-      "jmc.example.org": 
-        password: "jmcsecret"
-  - 
-    port: 5239
-    module: ejabberd_service
-    service_check_from: false
-    hosts: 
-      "custom.example.org": 
-        password: "customsecret"
-\end{verbatim}
-Note, that for services based in \ind{jabberd14}jabberd14 or \ind{WPJabber}WPJabber
-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.
-     In this case the transport will do the logging.
-  -->
-
-  <log id='logger'>
-    <host/>
-    <logtype/>
-    <format>%d: [%t] (%h): %s</format>
-    <file>/var/log/jabber/service.log</file>
-  </log>
-
-  <!--
-     Some XMPP server implementations do not provide
-     XDB services (for example, jabberd2 and ejabberd).
-     xdb_file.so is loaded in to handle all XDB requests.
-  -->
-
-  <xdb id="xdb">
-    <host/>
-    <load>
-      <!-- this is a lib of wpjabber or jabberd14 -->
-      <xdb_file>/usr/lib/jabber/xdb_file.so</xdb_file>
-      </load>
-    <xdb_file xmlns="jabber:config:xdb_file">
-      <spool><jabberd:cmdline flag='s'>/var/spool/jabber</jabberd:cmdline></spool>
-    </xdb_file>
-  </xdb>
-\end{verbatim}
-
-\makesubsection{auth}{Authentication}
-\ind{authentication}\ind{options!auth\_method}
-
-The option \option{auth\_method} defines the authentication methods that are used
-for user authentication. The syntax is:
-\esyntax{[Method, ...]}
-
-The following authentication methods are supported by \ejabberd{}:
-\begin{itemize}
-\item internal (default) --- See section~\ref{internalauth}.
-\item external --- See section~\ref{extauth}.
-\item ldap --- See section~\ref{ldap}.
-\item odbc --- See section~\ref{odbc}.
-\item anonymous --- See section~\ref{saslanonymous}.
-\item pam --- See section~\ref{pam}.
-\end{itemize}
-
-Account creation is only supported by internal, external and odbc methods.
-
-The option \option{resource\_conflict} defines the action when a client attempts to
-login to an account with a resource that is already connected.
-The option syntax is:
-\esyntax{resource\_conflict: setresource|closenew|closeold}
-The possible values match exactly the three possibilities described in
-\footahref{http://tools.ietf.org/html/rfc6120\#section-7.7.2.2}{XMPP Core: section 7.7.2.2}.
-The default value is \term{closeold}.
-If the client uses old Jabber Non-SASL authentication (\xepref{0078}),
-then this option is not respected, and the action performed is \term{closeold}.
-
-The option \option{fqdn} allows you to define the Fully Qualified Domain Name
-of the machine, in case it isn't detected automatically.
-The FQDN is used to authenticate some clients that use the DIGEST-MD5 SASL mechanism.
-The option syntax is:
-\esyntax{fqdn: undefined|FqdnString|[FqdnString]}
-
-The option \option{disable\_sasl\_mechanisms} specifies a list of SASL
-mechanisms that should \emph{not} be offered to the client. The mechanisms can
-be listed as lowercase or uppercase strings. The option syntax is:
-\esyntax{disable\_sasl\_mechanisms: [Mechanism, ...]}
-
-\makesubsubsection{internalauth}{Internal}
-\ind{internal authentication}\ind{Mnesia}
-
-\ejabberd{} uses its internal Mnesia database as the default authentication method.
-The value \term{internal} will enable the internal authentication method.
-
-The option \term{auth\_password\_format: plain|scram}
-defines in what format the users passwords are stored:
-\begin{description}
-    \titem{plain}
-    The password is stored as plain text in the database.
-    This is risky because the passwords can be read if your database gets compromised.
-    This is the default value.
-    This format allows clients to authenticate using:
-    the old Jabber Non-SASL (\xepref{0078}), \term{SASL PLAIN},
-    \term{SASL DIGEST-MD5}, and \term{SASL SCRAM-SHA-1}.
-
-    \titem{scram}
-    The password is not stored, only some information that allows to verify the hash provided by the client.
-    It is impossible to obtain the original plain password from the stored information;
-    for this reason, when this value is configured it cannot be changed to \term{plain} anymore.
-    This format allows clients to authenticate using: \term{SASL PLAIN} and \term{SASL SCRAM-SHA-1}.
-\end{description}
-
-Examples:
-\begin{itemize}
-\item To use internal authentication on \jid{example.org} and LDAP
-  authentication on \jid{example.net}:
-\begin{verbatim}
-host_config:
-  "example.org":
-    auth_method: [internal]
-  "example.net":
-    auth_method: [ldap]
-\end{verbatim}
-\item To use internal authentication with hashed passwords on all virtual hosts:
-\begin{verbatim}
-auth_method: internal
-auth_password_format: scram
-\end{verbatim}
-\end{itemize}
-
-\makesubsubsection{extauth}{External Script}
-\ind{external authentication}
-
-In this authentication method, when \ejabberd{} starts,
-it start a script, and calls it to perform authentication tasks.
-
-The server administrator can write the external authentication script
-in any language.
-The details on the interface between ejabberd and the script are described
-in the \term{ejabberd Developers Guide}.
-There are also \footahref{http://www.ejabberd.im/extauth}{several example authentication scripts}.
-
-These are the specific options:
-\begin{description}
-  \titem{extauth\_program: PathToScript} 
-  Indicate in this option the full path to the external authentication script.
-  The script must be executable by ejabberd.
-
-  \titem{extauth\_instances: Integer} 
-  Indicate how many instances of the script to run simultaneously to serve authentication in the virtual host.
-  The default value is the minimum number: 1.
-
-  \titem{extauth\_cache: false|CacheTimeInteger} 
-  The value \term{false} disables the caching feature, this is the default.
-  The integer \term{0} (zero) enables caching for statistics, but doesn't use that cached information to authenticate users.
-  If another integer value is set, caching is enabled both for statistics and for authentication:
-  the CacheTimeInteger indicates the number of seconds that ejabberd can reuse
-  the authentication information since the user last disconnected,
-  to verify again the user authentication without querying again the extauth script.
-  Note: caching should not be enabled in a host if internal auth is also enabled.
-  If caching is enabled, \term{mod\_last} must be enabled also in that vhost.
-\end{description}
-
-This example sets external authentication, the extauth script, enables caching for 10 minutes,
-and starts three instances of the script for each virtual host defined in ejabberd:
-\begin{verbatim}
-auth_method: [external]
-extauth_program: "/etc/ejabberd/JabberAuth.class.php"
-extauth_cache: 600
-extauth_instances: 3
-\end{verbatim}
-
-
-\makesubsubsection{saslanonymous}{Anonymous Login and SASL Anonymous}
-\ind{sasl anonymous}\ind{anonymous login}
-
-The \term{anonymous} authentication method enables two modes for anonymous authentication:
-\begin{description}
-\titem{Anonymous login:} This is a standard login, that use the
-  classical login and password mechanisms, but where password is
-  accepted or preconfigured for all anonymous users. This login is
-  compliant with SASL authentication, password and digest non-SASL
-  authentication, so this option will work with almost all XMPP
-  clients
-
-\titem{SASL Anonymous:} This is a special SASL authentication
-  mechanism that allows to login without providing username or
-  password (see \xepref{0175}).  The main advantage of SASL Anonymous
-  is that the protocol was designed to give the user a login. This is
-  useful to avoid in some case, where the server has many users
-  already logged or registered and when it is hard to find a free
-  username. The main disavantage is that you need a client that
-  specifically supports the SASL Anonymous protocol.
-\end{description}
-
-%TODO: introduction; tell what people can do with this
-The anonymous authentication method can be configured with the following
-options. Remember that you can use the \term{host\_config} option to set virtual
-host specific options (see section~\ref{virtualhost}).
-
-\begin{description}
-\titem{allow\_multiple\_connections: false|true} This option is only used
-  when the anonymous mode is
-  enabled. Setting it to \term{true} means that the same username can be taken
-  multiple times in anonymous login mode if different resource are used to
-  connect. This option is only useful in very special occasions. The default
-  value is \term{false}.
-\titem{anonymous\_protocol: login\_anon | sasl\_anon | both}
-  \term{login\_anon} means that the anonymous login method will be used.
-  \term{sasl\_anon} means that the SASL Anonymous method will be used.
-  \term{both} means that SASL Anonymous and login anonymous are both enabled.
-\end{description}
-
-Those options are defined for each virtual host with the \term{host\_config}
-parameter (see section~\ref{virtualhost}).
-
-Examples:
-\begin{itemize}
-\item To enable anonymous login on all virtual hosts:
-\begin{verbatim}
-auth_method: [anonymous]
-anonymous_protocol: login_anon
-\end{verbatim}
-\item Similar as previous example, but limited to \jid{public.example.org}:
-\begin{verbatim}
-host_config:
-  "public.example.org":
-    auth_method: [anonymous]
-    anonymous_protoco: login_anon
-\end{verbatim}
-\item To enable anonymous login and internal authentication on a virtual host:
-\begin{verbatim}
-host_config:
-  "public.example.org":
-    auth_method:
-      - internal
-      - anonymous
-    anonymous_protocol: login_anon
-\end{verbatim}
-\item To enable SASL Anonymous on a virtual host:
-\begin{verbatim}
-host_config:
-  "public.example.org":
-    auth_method: [anonymous]
-    anonymous_protocol: sasl_anon
-\end{verbatim}
-\item To enable SASL Anonymous and anonymous login on a virtual host:
-\begin{verbatim}
-host_config:
-  "public.example.org":
-    auth_method: [anonymous]
-    anonymous_protocol: both
-\end{verbatim}
-\item To enable SASL Anonymous, anonymous login, and internal authentication on
-a virtual host:
-\begin{verbatim}
-host_config:
-  "public.example.org":
-    auth_method:
-      - internal
-      - anonymous
-    anonymous_protocol: both
-\end{verbatim}
-\end{itemize}
-
-There are more configuration examples and XMPP client example stanzas in
-\footahref{http://www.ejabberd.im/Anonymous-users-support}{Anonymous users support}.
-
-
-\makesubsubsection{pam}{PAM Authentication}
-\ind{PAM authentication}\ind{Pluggable Authentication Modules}
-
-\ejabberd{} supports authentication via Pluggable Authentication Modules (PAM).
-PAM is currently supported in AIX, FreeBSD, HP-UX, Linux, Mac OS X, NetBSD and Solaris.
-PAM authentication is disabled by default, so you have to configure and compile
-\ejabberd{} with PAM support enabled:
-\begin{verbatim}
-./configure --enable-pam && make install
-\end{verbatim}
-
-Options:
-\begin{description}
-\titem{pam\_service: Name}\ind{options!pam\_service}This option defines the PAM service name.
-Default is \term{"ejabberd"}. Refer to the PAM documentation of your operation system
-for more information.
-\titem{pam\_userinfotype: username|jid}\ind{options!pam\_userinfotype}
-This option defines what type of information about the user ejabberd
-provides to the PAM service: only the username, or the user JID.
-Default is \term{username}.
-\end{description}
-
-Example:
-\begin{verbatim}
-auth_method: [pam]
-pam_service: "ejabberd"
-\end{verbatim}
-
-Though it is quite easy to set up PAM support in \ejabberd{}, PAM itself introduces some
-security issues:
-
-\begin{itemize}
-\item To perform PAM authentication \ejabberd{} uses external C-program called
-\term{epam}. By default, it is located in \verb|/var/lib/ejabberd/priv/bin/|
-directory. You have to set it root on execution in the case when your PAM module
-requires root privileges (\term{pam\_unix.so} for example). Also you have to grant access
-for \ejabberd{} to this file and remove all other permissions from it.
-Execute with root privileges:
-\begin{verbatim}
-chown root:ejabberd /var/lib/ejabberd/priv/bin/epam
-chmod 4750 /var/lib/ejabberd/priv/bin/epam
-\end{verbatim}
-\item Make sure you have the latest version of PAM installed on your system.
-Some old versions of PAM modules cause memory leaks. If you are not able to use the latest
-version, you can \term{kill(1)} \term{epam} process periodically to reduce its memory
-consumption: \ejabberd{} will restart this process immediately.
-\item \term{epam} program tries to turn off delays on authentication failures.
-However, some PAM modules ignore this behavior and rely on their own configuration options.
-You can create a configuration file \term{ejabberd.pam}.
-This example shows how to turn off delays in \term{pam\_unix.so} module:
-\begin{verbatim}
-#%PAM-1.0
-auth        sufficient  pam_unix.so likeauth nullok nodelay
-account     sufficient  pam_unix.so
-\end{verbatim}
-That is not a ready to use configuration file: you must use it
-as a hint when building your own PAM configuration instead. Note that if you want to disable
-delays on authentication failures in the PAM configuration file, you have to restrict access
-to this file, so a malicious user can't use your configuration to perform brute-force
-attacks.
-\item You may want to allow login access only for certain users. \term{pam\_listfile.so}
-module provides such functionality.
-\item If you use \term{pam\_winbind} to authorise against a Windows Active Directory,
-then \term{/etc/nsswitch.conf} must be configured to use \term{winbind} as well.
-\end{itemize}
-
-\makesubsection{accessrules}{Access Rules}
-\ind{access rules}\ind{ACL}\ind{Access Control List}
-
-\makesubsubsection{ACLDefinition}{ACL Definition}
-\ind{ACL}\ind{options!acl}\ind{ACL}\ind{Access Control List}
-
-Access control in \ejabberd{} is performed via Access Control Lists (ACLs). The
-declarations of ACLs in the configuration file have the following syntax:
-\esyntax{acl: \{ ACLName: \{ ACLType: ACLValue \} \}}
-
-\term{ACLType: ACLValue} can be one of the following:
-\begin{description}
-\titem{all} Matches all JIDs. Example:
-\begin{verbatim}
-acl:
-  world: all
-\end{verbatim}
-\titem{user: Username} Matches the user with the name
-  \term{Username} at the first virtual host. Example:
-\begin{verbatim}
-acl:
-  admin:
-    user: "yozhik"
-\end{verbatim}
-\titem{user: \{Username: Server\}} Matches the user with the JID
-  \term{Username@Server} and any resource. Example:
-\begin{verbatim}
-acl:
-  admin:
-    user:
-      "yozhik": "example.org"
-\end{verbatim}
-\titem{server: Server} Matches any JID from server
-  \term{Server}. Example:
-\begin{verbatim}
-acl:
-  exampleorg:
-    server: "example.org"
-\end{verbatim}
-\titem{resource: Resource} Matches any JID with a resource
-  \term{Resource}. Example:
-\begin{verbatim}
-acl:
-  mucklres:
-   resource: "muckl"
-\end{verbatim}
-\titem{shared\_group: Groupname} Matches any member of a Shared Roster Group with name \term{Groupname} in the virtual host. Example:
-\begin{verbatim}
-acl:
-  techgroupmembers:
-    shared_group: "techteam"
-\end{verbatim}
-\titem{shared\_group: \{Groupname: Server\}} Matches any member of a Shared Roster Group with name \term{Groupname} in the virtual host \term{Server}. Example:
-\begin{verbatim}
-acl:
-  techgroupmembers:
-    shared_group:
-      "techteam": "example.org"
-\end{verbatim}
-\titem{ip: Network} Matches any IP address from the \term{Network}. Example:
-\begin{verbatim}
-acl:
-  loopback:
-    ip:
-      - "127.0.0.0/8"
-      - "::1"
-\end{verbatim}
-\titem{user\_regexp: Regexp} Matches any local user with a name that
-  matches \term{Regexp} on local virtual hosts. Example:
-\begin{verbatim}
-acl:
-  tests:
-    user_regexp: "^test[0-9]*$"
-\end{verbatim}
-%$
-\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_regexp:
-      "^test": "example.org"
-\end{verbatim}
-\titem{server\_regexp: Regexp} Matches any JID from the server that
-  matches \term{Regexp}. Example:
-\begin{verbatim}
-acl:
-  icq:
-    server_regexp: "^icq\\."
-\end{verbatim}
-\titem{resource\_regexp: Regexp} Matches any JID with a resource that
-  matches \term{Regexp}. Example:
-\begin{verbatim}
-acl:
-  icq:
-    resource_regexp: "^laptop\\."
-\end{verbatim}
-\titem{node\_regexp: \{UserRegexp: ServerRegexp\}} Matches any user
-  with a name that matches \term{UserRegexp} at any server that matches
-  \term{ServerRegexp}. Example:
-\begin{verbatim}
-acl:
-  yozhik:
-    node_regexp:
-      "^yozhik$": "^example.(com|org)$"
-\end{verbatim}
-\titem{user\_glob: Glob\}}
-\titem{user\_glob: \{Glob: Server\}}
-\titem{server\_glob: Glob}
-\titem{resource\_glob: Glob}
-\titem{node\_glob: \{UserGlob: ServerGlob\}} 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
-    ranges are specified by a pair of characters separated by a \term{`-'}.
-    If the first character after \term{`['} is a \term{`!'}, any
-    character not enclosed is matched.
-  \end{description}
-\end{description}
-
-The following \term{ACLName} are pre-defined:
-\begin{description}
-\titem{all} Matches any JID.
-\titem{none} Matches no JID.
-\end{description}
-
-\makesubsubsection{AccessRights}{Access Rights}
-\ind{access}\ind{ACL}\ind{options!acl}\ind{ACL}\ind{Access Control List}
-
-An entry allowing or denying access to different services.
-The syntax is:
-\esyntax{access: \{ AccessName: \{ ACLName: allow|deny \} \}}
-
-When a JID is checked to have access to \term{Accessname}, the server
-sequentially checks if that JID matches any of the ACLs that are named in the
-first elements of the tuples in the list. If it matches, the second element of
-the first matched tuple is returned, otherwise the value `\term{deny}' is
-returned.
-
-If you define specific Access rights in a virtual host,
-remember that the globally defined Access rights have precedence over those.
-This means that, in case of conflict, the Access granted or denied in the global server is used
-and the Access of a virtual host doesn't have effect.
-
-Example:
-\begin{verbatim}
-access:
-  configure:
-    admin: allow
-  something
-    badmans: deny
-    all: allow
-\end{verbatim}
-
-The following \term{AccessName} are pre-defined:
-\begin{description}
-\titem{all} Always returns the value `\term{allow}'.
-\titem{none} Always returns the value `\term{deny}'.
-\end{description}
-
-\makesubsubsection{configmaxsessions}{Limiting Opened Sessions with ACL}
-\ind{options!max\_user\_sessions}
-
-The special access \term{max\_user\_sessions} specifies the maximum
-number of sessions (authenticated connections) per user. If a user
-tries to open more sessions by using different resources, the first
-opened session will be disconnected. The error \term{session replaced}
-will be sent to the disconnected session. The value for this option
-can be either a number, or \term{infinity}.  The default value is
-\term{infinity}.
-
-The syntax is:
-\esyntax{\{ max\_user\_sessions: \{ ACLName: MaxNumber \} \}}
-
-This example limits the number of sessions per user to 5 for all users, and to 10 for admins:
-\begin{verbatim}
-access:
-  max_user_sessions:
-    admin: 10
-    all: 5
-\end{verbatim}
-
-\makesubsubsection{configmaxs2sconns}{Several connections to a remote XMPP server with ACL}
-\ind{options!max\_s2s\_connections}
-
-The special access \term{max\_s2s\_connections} specifies how many
-simultaneous S2S connections can be established to a specific remote XMPP server.
-The default value is \term{1}.
-There's also available the access \term{max\_s2s\_connections\_per\_node}.
-
-The syntax is:
-\esyntax{\{ max\_s2s\_connections: \{ ACLName: MaxNumber \} \}}
-
-Examples:
-\begin{itemize}
-\item Allow up to 3 connections with each remote server:
-\begin{verbatim}
-access:
-  max_s2s_connections:
-    all: 3
-\end{verbatim}
-\end{itemize}
-
-\makesubsection{shapers}{Shapers}
-\ind{options!shaper}\ind{shapers}\ind{traffic speed}
-
-Shapers enable you to limit connection traffic.
-The syntax is:
-\esyntax{shaper: \{ ShaperName: Rate \}}
-where \term{Rate} stands for the maximum allowed incoming rate in bytes per
-second.
-When a connection exceeds this limit, \ejabberd{} stops reading from the socket
-until the average rate is again below the allowed maximum.
-
-Examples:
-\begin{itemize}
-\item To define a shaper named `\term{normal}' with traffic speed limited to
-1,000\,bytes/second:
-\begin{verbatim}
-shaper:
-  normal: 1000
-\end{verbatim}
-\item To define a shaper named `\term{fast}' with traffic speed limited to
-50,000\,bytes/second:
-\begin{verbatim}
-shaper:
-  fast: 50000
-\end{verbatim}
-\end{itemize}
-
-\makesubsection{language}{Default Language}
-\ind{options!language}\ind{language}
-
-The option \option{language} defines the default language of server strings that
-can be seen by \XMPP{} clients. If a \XMPP{} client does not support
-\option{xml:lang}, the specified language is used.
-
-The option syntax is:
-\esyntax{language: Language}
-
-The default value is \term{en}.
-In order to take effect there must be a translation file
-\term{Language.msg} in \ejabberd{}'s \term{msgs} directory.
-
-For example, to set Russian as default language:
-\begin{verbatim}
-language: "ru"
-\end{verbatim}
-
-Appendix \ref{i18ni10n} provides more details about internationalization and localization.
-
-
-\makesubsection{captcha}{CAPTCHA}
-\ind{options!captcha}\ind{captcha}
-
-Some \ejabberd{} modules can be configured to require a CAPTCHA challenge on certain actions.
-If the client does not support CAPTCHA Forms (\xepref{0158}),
-a web link is provided so the user can fill the challenge in a web browser.
-
-An example script is provided that generates the image
-using ImageMagick's Convert program.
-
-The configurable options are:
-\begin{description}
-  \titem{captcha\_cmd: Path} 
-  Full path to a script that generates the image.
-  The default value disables the feature: \term{undefined}
-  \titem{captcha\_host: ProtocolHostPort} 
-  ProtocolHostPort is a string with the host, and optionally the Protocol and Port number.
-  It must identify where ejabberd listens for CAPTCHA requests.
-  The URL sent to the user is formed by: \term{Protocol://Host:Port/captcha/}
-  The default value is: protocol \term{http}, the first hostname configured, and port \term{80}.
-  If you specify a port number that does not match exactly an ejabberd listener
-  (because you are using a reverse proxy or other port-forwarding tool),
-  then you must specify the transfer protocol, as seen in the example below.
-\end{description}
-
-Additionally, an \term{ejabberd\_http} listener must be enabled with the \term{captcha} option.
-See section \ref{listened-module}.
-
-Example configuration:
-\begin{verbatim}
-hosts: ["example.org"]
-
-captcha_cmd: "/lib/ejabberd/priv/bin/captcha.sh"
-captcha_host: "example.org:5280"
-## captcha_host: "https://example.org:443"
-## captcha_host: "http://example.com"
-
-listen:
-  ...
-  -
-    port: 5280
-    module: ejabberd_http
-    captcha: true
-  ...
-\end{verbatim}
-
-\makesubsection{stun}{STUN and TURN}
-\ind{options!stun}\ind{stun}
-
-\ejabberd{} is able to act as a stand-alone STUN/TURN server
-(\footahref{http://tools.ietf.org/html/rfc5389}{RFC 5389}/\footahref{http://tools.ietf.org/html/rfc5766}{RFC 5766}). In that role \ejabberd{} helps clients with ICE (\footahref{http://tools.ietf.org/html/rfc5245}{RFC 5245}) or Jingle ICE (\xepref{0176}) support to discover their external addresses and ports and to relay media traffic when it is impossible to establish direct
-peer-to-peer connection.
-
-You should configure \term{ejabberd\_stun} listening module as described in \ref{listened} section.
-The specific configurable options are:
-\begin{description}
-  \titem{tls: true|false}
-  If enabled, \option{certfile} option must be set, otherwise \ejabberd{}
-  will not be able to accept TLS connections. Obviously, this option
-  makes sense for \term{tcp} transport only. The default is \term{false}.
-  \titem{certfile: Path}
-  Path to the certificate file. Only makes sense when \option{tls} is set.
-  \titem{use\_turn: true|false}
-  Enables/disables TURN (media relay) functionality. The default is \term{false}.
-  \titem{turn\_ip: String}
-  The IPv4 address advertised by your TURN server. The address should not be NAT'ed
-  or firewalled. There is not default, so you should set this option explicitly.
-  Implies \term{use\_turn}.
-  \titem{turn\_min\_port: Integer}
-  Together with \option{turn\_max\_port} forms port range to allocate from.
-  The default is 49152. Implies \term{use\_turn}.
-  \titem{turn\_max\_port: Integer}
-  Together with \option{turn\_min\_port} forms port range to allocate from.
-  The default is 65535. Implies \term{use\_turn}.
-  \titem{turn\_max\_allocations: Integer|infinity}
-  Maximum number of TURN allocations available from the particular IP address.
-  The default value is 10. Implies \term{use\_turn}.
-  \titem{turn\_max\_permissions: Integer|infinity}
-  Maximum number of TURN permissions available from the particular IP address.
-  The default value is 10. Implies \term{use\_turn}.
-  \titem{auth\_type: user|anonymous}
-  Which authentication type to use for TURN allocation requests. When type \term{user}
-  is set, ejabberd authentication backend is used. For \term{anonymous} type
-  no authentication is performed (not recommended for public services).
-  The default is \term{user}. Implies \term{use\_turn}.
-  \titem{auth\_realm: String}
-  When \option{auth\_type} is set to \term{user} and you have several virtual
-  hosts configured you should set this option explicitly to the virtual host
-  you want to serve on this particular listening port. Implies \term{use\_turn}.
-  \titem{shaper: Atom}
-  For \term{tcp} transports defines shaper to use. The default is \term{none}.
-  \titem{server\_name: String}
-  Defines software version to return with every response. The default is the
-  STUN library version.
-\end{description}
-
-Example configuration with disabled TURN functionality (STUN only):
-\begin{verbatim}
-listen:
-  ...
-  - 
-    port: 3478
-    transport: udp
-    module: ejabberd_stun
-  - 
-    port: 3478
-    module: ejabberd_stun
-  -
-    port: 5349
-    module: ejabberd_stun
-    certfile: "/etc/ejabberd/server.pem"
-  ...
-\end{verbatim}
-
-Example configuration with TURN functionality. Note that STUN is always
-enabled if TURN is enabled. Here, only UDP section is shown:
-\begin{verbatim}
-listen:
-  ...
-  - 
-    port: 3478
-    transport: udp
-    use_turn: true
-    turn_ip: "10.20.30.1"
-    module: ejabberd_stun
-  ...
-\end{verbatim}
-
-You also need to configure DNS SRV records properly so clients can easily discover a
-STUN/TURN server serving your XMPP domain. Refer to section
-\footahref{http://tools.ietf.org/html/rfc5389\#section-9}{DNS Discovery of a Server}
-of \footahref{http://tools.ietf.org/html/rfc5389}{RFC 5389} and section
-\footahref{http://tools.ietf.org/html/rfc5766\#section-6}{Creating an Allocation}
-of \footahref{http://tools.ietf.org/html/rfc5766}{RFC 5766} for details.
-
-Example DNS SRV configuration for STUN only:
-\begin{verbatim}
-_stun._udp   IN SRV  0 0 3478 stun.example.com.
-_stun._tcp   IN SRV  0 0 3478 stun.example.com.
-_stuns._tcp  IN SRV  0 0 5349 stun.example.com.
-\end{verbatim}
-
-And you should also add these in the case if TURN is enabled:
-\begin{verbatim}
-_turn._udp   IN SRV  0 0 3478 turn.example.com.
-_turn._tcp   IN SRV  0 0 3478 turn.example.com.
-_turns._tcp  IN SRV  0 0 5349 turn.example.com.
-\end{verbatim}
-
-\makesubsection{sip}{SIP}
-\ind{options!sip}\ind{sip}
-
-\ejabberd{} has built-in SIP support. In order to activate it you need to add
-listeners for it, configure DNS properly and enable \modsip{} for
-the desired virtual host.
-
-To add a listener you should configure \term{ejabberd\_sip} listening module as
-described in \ref{listened} section. If option \option{tls} is specified, option
-\option{certfile} must be specified as well, otherwise incoming TLS connections would fail.
-
-Example configuration with standard ports
-(as per \footahref{http://tools.ietf.org/html/rfc3261}{RFC 3261}):
-\begin{verbatim}
-listen:
-  ...
-  - 
-    port: 5060
-    transport: udp
-    module: ejabberd_sip
-  - 
-    port: 5060
-    module: ejabberd_sip
-  -
-    port: 5061
-    module: ejabberd_sip
-    tls: true
-    certfile: "/etc/ejabberd/server.pem"
-  ...
-\end{verbatim}
-
-Note that there is no StartTLS support in SIP and \footahref{http://en.wikipedia.org/wiki/Server\_Name\_Indication}{SNI} support is somewhat tricky, so for TLS you have to configure
-different virtual hosts on different ports if you have different certificate files for them.
-
-Next you need to configure DNS SIP records for your virtual domains.
-Refer to \footahref{http://tools.ietf.org/html/rfc3263}{RFC 3263} for the detailed explanation.
-Simply put, you should add NAPTR and SRV records for your domains.
-Skip NAPTR configuration if your DNS provider doesn't support this type of records.
-It's not fatal, however, highly recommended.
-
-Example configuration of NAPTR records:
-\begin{verbatim}
-example.com IN NAPTR 10  0 "s" "SIPS+D2T" "" _sips._tcp.example.com.
-example.com IN NAPTR 20  0 "s" "SIP+D2T" "" _sip._tcp.example.com.
-example.com IN NAPTR 30  0 "s" "SIP+D2U" "" _sip._udp.example.com.
-\end{verbatim}
-
-Example configuration of SRV records with standard ports
-(as per \footahref{http://tools.ietf.org/html/rfc3261}{RFC 3261}):
-\begin{verbatim}
-_sip._udp   IN SRV  0 0 5060 sip.example.com.
-_sip._tcp   IN SRV  0 0 5060 sip.example.com.
-_sips._tcp  IN SRV  0 0 5061 sip.example.com.
-\end{verbatim}
-
-\makesubsection{includeconfigfile}{Include Additional Configuration Files}
-\ind{options!includeconfigfile}\ind{includeconfigfile}
-
-The option \option{include\_config\_file} in a configuration file instructs \ejabberd{} to include other configuration files immediately.
-
-The basic syntax is:
-\esyntax{include\_config\_file: [Filename]}
-It is possible to specify suboptions using the full syntax:
-\esyntax{include\_config\_file: \{ Filename: [Suboption, ...] \}}
-
-The filename can be indicated either as an absolute path,
-or relative to the main \ejabberd{} configuration file.
-It isn't possible to use wildcards.
-The file must exist and be readable.
-
-The allowed suboptions are:
-\begin{description}
-  \titem{disallow: [Optionname, ...]} Disallows the usage of those options in the included configuration file.
-  The options that match this criteria are not accepted.
-  The default value is an empty list: \term{[]}
-  \titem{allow\_only: [Optionname, ...]} Allows only the usage of those options in the included configuration file.
-  The options that do not match this criteria are not accepted.
-  The default value is: \term{all}
-\end{description}
-
-This is a basic example:
-\begin{verbatim}
-include_config_file: "/etc/ejabberd/additional.yml"
-\end{verbatim}
-
-In this example, the included file is not allowed to contain a \term{listen} option.
-If such an option is present, the option will not be accepted.
-The file is in a subdirectory from where the main configuration file is.
-\begin{verbatim}
-include_config_file:
-  "./example.org/additional_not_listen.yml":
-    disallow: [listen]
-\end{verbatim}
-
-In this example, \term{ejabberd.yml} defines some ACL and Access rules,
-and later includes another file with additional rules:
-\begin{verbatim}
-acl:
-  admin:
-    user:
-      - "admin": "localhost"
-access:
-  announce:
-    admin: allow
-include_config_file:
-  "/etc/ejabberd/acl_and_access.yml":
-    allow_only:
-      - acl
-      - access
-\end{verbatim}
-and content of the file \term{acl\_and\_access.yml} can be, for example:
-\begin{verbatim}
-acl:
-  admin:
-    user:
-      - "bob": "localhost"
-      - "jan": "localhost"
-\end{verbatim}
-
-
-\makesubsection{optionmacros}{Option Macros in Configuration File}
-\ind{options!optionmacros}\ind{optionmacros}
-
-In the \ejabberd{} configuration file,
-it is possible to define a macro for a value
-and later use this macro when defining an option.
-
-A macro is defined with this syntax:
-\esyntax{define\_macro: \{ 'MACRO': Value \}}
-The \term{MACRO} must be surrounded by single quotation marks,
-and all letters in uppercase; check the examples bellow.
-The \term{value} can be any valid arbitrary Erlang term.
-
-The first definition of a macro is preserved,
-and additional definitions of the same macro are forgotten.
-
-Macros are processed after
-additional configuration files have been included,
-so it is possible to use macros that
-are defined in configuration files included before the usage.
-
-It isn't possible to use a macro in the definition
-of another macro.
-
-This example shows the basic usage of a macro:
-\begin{verbatim}
-define_macro:
-  'LOG_LEVEL_NUMBER': 5
-loglevel: 'LOG_LEVEL_NUMBER'
-\end{verbatim}
-The resulting option interpreted by \ejabberd{} is: \term{loglevel: 5}.
-
-This example shows that values can be any arbitrary Erlang term:
-\begin{verbatim}
-define_macro:
-  'USERBOB':
-    user:
-      - "bob": "localhost"
-acl:
-  admin: 'USERBOB'
-\end{verbatim}
-The resulting option interpreted by \ejabberd{} is:
-\begin{verbatim}
-acl:
-  admin:
-    user:
-      - "bob": "localhost"
-\end{verbatim}
-This complex example:
-\begin{verbatim}
-define_macro:
-  'NUMBER_PORT_C2S': 5222
-  'NUMBER_PORT_HTTP': 5280
-listen:
-  - 
-    port: 'NUMBER_PORT_C2S'
-    module: ejabberd_c2s
-  - 
-    port: 'NUMBER_PORT_HTTP'
-    module: ejabberd_http
-\end{verbatim}
-produces this result after being interpreted:
-\begin{verbatim}
-listen:
-  - 
-    port: 5222
-    module: ejabberd_c2s
-  - 
-    port: 5280
-    module: ejabberd_http
-\end{verbatim}
-\makesection{database}{Database and LDAP Configuration}
-\ind{database}
-%TODO: this whole section is not yet 100% optimized
-
-\ejabberd{} uses its internal Mnesia database by default. However, it is
-possible to use a relational database, key-value storage or an LDAP server to store persistent,
-long-living data. \ejabberd{} is very flexible: you can configure different
-authentication methods for different virtual hosts, you can configure different
-authentication mechanisms for the same virtual host (fallback), you can set
-different storage systems for modules, and so forth.
-
-The following databases are supported by \ejabberd{}:
-\begin{itemize}
-%%\item \footahref{http://www.microsoft.com/sql/}{Microsoft SQL Server}
-\item \footahref{http://www.erlang.org/doc/apps/mnesia/index.html}{Mnesia}
-\item \footahref{http://www.mysql.com/}{MySQL}
-\item \footahref{http://en.wikipedia.org/wiki/Open\_Database\_Connectivity}{Any ODBC compatible database}
-\item \footahref{http://www.postgresql.org/}{PostgreSQL}
-\item \footahref{http://basho.com/riak/}{Riak}
-\end{itemize}
-
-The following LDAP servers are tested with \ejabberd{}:
-\begin{itemize}
-\item \footahref{http://www.microsoft.com/activedirectory/}{Active Directory}
-  (see section~\ref{ad})
-\item \footahref{http://www.openldap.org/}{OpenLDAP}
-\item \footahref{http://www.communigate.com/}{CommuniGate Pro}
-\item Normally any LDAP compatible server should work; inform us about your
-  success with a not-listed server so that we can list it here.
-\end{itemize}
-
-Important note about virtual hosting:
-if you define several domains in ejabberd.yml (see section \ref{hostnames}),
-you probably want that each virtual host uses a different configuration of database, authentication and storage,
-so that usernames do not conflict and mix between different virtual hosts.
-For that purpose, the options described in the next sections
-must be set inside a \term{host\_config} for each vhost (see section \ref{virtualhost}).
-For example:
-\begin{verbatim}
-host_config:
-  "public.example.org":
-    odbc_type: pgsql
-    odbc_server: "localhost"
-    odbc_database: "database-public-example-org"
-    odbc_username: "ejabberd"
-    odbc_password: "password"
-    auth_method: [odbc]
-\end{verbatim}
-
-
-\makesubsection{odbc}{ODBC}\ind{odbc}
-
-The actual database access is defined in the options with \term{odbc\_} prefix. The
-values are used to define if we want to use ODBC, or one of the two native
-interface available, PostgreSQL or MySQL.
-
-The following paramaters are available:
-\begin{description}
-  \titem{odbc\_type: mysql | pgsql | odbc} The type of an ODBC connection.
-  The default is \term{odbc}.
-  \titem{odbc\_server: String} A hostname of the ODBC server. The default is
-  \term{``localhost''}.
-  \titem{odbc\_port: Port} The port where the ODBC server is accepting connections.
-  The option is only valid for \term{mysql} and \term{pgsql}. The default is
-  \term{3306} and \term{5432} respectively.
-  \titem{odbc\_database: String} The database name. The default is \term{``ejabberd''}.
-  The option is only valid for \term{mysql} and \term{pgsql}.
-  \titem{odbc\_username: String} The username. The default is \term{``ejabberd''}.
-  The option is only valid for \term{mysql} and \term{pgsql}. 
-  \titem{odbc\_password: String} The password. The default is empty string.
-  The option is only valid for \term{mysql} and \term{pgsql}.
-  \titem{odbc\_pool\_size: N} By default \ejabberd{} opens 10 connections to
-  the database for each virtual host. You can change this number by using this option.
-  \titem{odbc\_keepalive\_interval: N} You can configure an interval to
-  make a dummy SQL request to keep alive the connections to the database.
-  The default value is 'undefined', so no keepalive requests are made.
-  Specify in seconds: for example 28800 means 8 hours.
-  \titem{odbc\_start\_interval: N} If the connection to the database fails,
-  \ejabberd{} waits 30 seconds before retrying.
-  You can modify this interval with this option.
-\end{description}
-
-Example of plain ODBC connection:
-\begin{verbatim}
-odbc_server: "DSN=database;UID=ejabberd;PWD=password"
-\end{verbatim}
-
-Example of MySQL connection:
-\begin{verbatim}
-odbc_type: mysql
-odbc_server: "server.company.com"
-odbc_port: 3306 # the default
-odbc_database: "mydb"
-odbc_username: "user1"
-odbc_password: "**********"
-odbc_pool_size: 5
-\end{verbatim}
-
-\makesubsubsection{odbcstorage}{Storage}
-\ind{ODBC!storage}
-
-An ODBC compatible database also can be used to store information into from
-several \ejabberd{}
-modules. See section~\ref{modoverview} to see which modules can be used with
-relational databases like MySQL. To enable storage to your database, just make
-sure that your database is running well (see previous sections), and add the
-module option \term{db\_type: odbc}.
-
-\makesubsection{ldap}{LDAP}
-\ind{databases!LDAP}
-
-\ejabberd{} has built-in LDAP support. You can authenticate users against LDAP
-server and use LDAP directory as vCard storage.
-
-Usually \ejabberd{} treats LDAP as a read-only storage:
-it is possible to consult data, but not possible to
-create accounts or edit vCard that is stored in LDAP.
-However, it is possible to change passwords if \module{mod\_register} module is enabled
-and LDAP server supports
-\footahref{http://tools.ietf.org/html/rfc3062}{RFC 3062}.
-
-
-\makesubsubsection{ldapconnection}{Connection}
-
-Two connections are established to the LDAP server per vhost,
-one for authentication and other for regular calls.
-
-Parameters:
-\begin{description}
-\titem{ldap\_servers: [Servers, ...]} \ind{options!ldap\_server}List of IP addresses or DNS names of your
-LDAP servers. This option is required.
-\titem{ldap\_encrypt: none|tls} \ind{options!ldap\_encrypt}Type of connection encryption to the LDAP server.
-Allowed values are: \term{none}, \term{tls}.
-The value \term{tls} enables encryption by using LDAP over SSL.
-Note that STARTTLS encryption is not supported.
-The default value is: \term{none}.
-\titem{ldap\_tls\_verify: false|soft|hard} \ind{options!ldap\_tls\_verify}
-This option specifies whether to verify LDAP server certificate or not when TLS is enabled.
-When \term{hard} is enabled \ejabberd{} doesn't proceed if a certificate is invalid.
-When \term{soft} is enabled \ejabberd{} proceeds even if check fails.
-The default is \term{false} which means no checks are performed.
-\titem{ldap\_tls\_cacertfile: Path} \ind{options!ldap\_tls\_cacertfile}
-Path to file containing PEM encoded CA certificates. This option is needed
-(and required) when TLS verification is enabled.
-\titem{ldap\_tls\_depth: Number} \ind{options!ldap\_tls\_depth}
-Specifies the maximum verification depth when TLS verification is enabled,
-i.e. how far in a chain of certificates the verification process can proceed
-before the verification is considered to fail.
-Peer certificate = 0, CA certificate = 1, higher level CA certificate = 2, etc.
-The value 2 thus means that a chain can at most contain peer cert,
-CA cert, next CA cert, and an additional CA cert. The default value is 1.
-\titem{ldap\_port: Number} \ind{options!ldap\_port}Port to connect to your LDAP server.
-The default port is~389 if encryption is disabled; and 636 if encryption is enabled.
-If you configure a value, it is stored in \ejabberd{}'s database.
-Then, if you remove that value from the configuration file,
-the value previously stored in the database will be used instead of the default port.
-\titem{ldap\_rootdn: RootDN} \ind{options!ldap\_rootdn}Bind DN. The default value
-  is~\term{""} which means `anonymous connection'.
-\titem{ldap\_password: Password} \ind{options!ldap\_password}Bind password. The default
-  value is \term{""}.
-\titem{ldap\_deref\_aliases: never|always|finding|searching} \ind{options!ldap\_deref\_aliases} Whether or not to dereference aliases. The default is \term{never}.
-\end{description}
-
-Example:
-\begin{verbatim}
-auth_method: [ldap]
-ldap_servers:
-  - "ldap1.example.org"
-ldap_port: 389
-ldap_rootdn: "cn=Manager,dc=domain,dc=org"
-ldap_password: "**********"
-\end{verbatim}
-
-\makesubsubsection{ldapauth}{Authentication}
-
-You can authenticate users against an LDAP directory. 
-Note that current LDAP implementation does not support SASL authentication.
-
-Available options are:
-
-\begin{description}
-\titem{ldap\_base: Base}\ind{options!ldap\_base}LDAP base directory which stores
-  users accounts. This option is required.
-  \titem{ldap\_uids: [ ldap\_uidattr | \{ldap\_uidattr: ldap\_uidattr\_format\} ]}\ind{options!ldap\_uids}
-  LDAP attribute which holds a list of attributes to use as alternatives for getting the JID. 
-  The default attributes are \term{[\{"uid", "\%u"\}]}.
-  The attributes are of the form:
-  \term{[\{ldap\_uidattr\}]} or \term{[\{ldap\_uidattr, ldap\_uidattr\_format\}]}.
-  You can use as many comma separated attributes as needed. 
-  The values for \term{ldap\_uidattr} and
-  \term{ldap\_uidattr\_format} are described as follow:
-  \begin{description}
-    \titem{ldap\_uidattr}\ind{options!ldap\_uidattr}LDAP attribute which holds
-    the user's part of a JID. The default value is \term{"uid"}.
-    \titem{ldap\_uidattr\_format}\ind{options!ldap\_uidattr\_format}Format of
-    the \term{ldap\_uidattr} variable. The format \emph{must} contain one and
-    only one pattern variable \term{"\%u"} which will be replaced by the
-    user's part of a JID. For example, \term{"\%u@example.org"}. The default
-    value is \term{"\%u"}.
-  \end{description}
-  \titem{ldap\_filter: Filter}\ind{options!ldap\_filter}\ind{protocols!RFC 4515:
-  LDAP String Representation of Search Filters}
-  \footahref{http://tools.ietf.org/html/rfc4515}{RFC 4515} LDAP filter. The
-  default Filter value is: \term{undefined}. Example:
-  \term{"(\&(objectClass=shadowAccount)(memberOf=Jabber Users))"}. Please, do
-  not forget to close brackets and do not use superfluous whitespaces. Also you
-  \emph{must not} use \option{ldap\_uidattr} attribute in filter because this
-  attribute will be substituted in LDAP filter automatically.
-  \titem{ldap\_dn\_filter: \{ Filter: FilterAttrs \}}\ind{options!ldap\_dn\_filter}
-  This filter is applied on the results returned by the main filter. This filter
-  performs additional LDAP lookup to make the complete result. This is useful
-  when you are unable to define all filter rules in \term{ldap\_filter}. You
-  can define \term{"\%u"}, \term{"\%d"}, \term{"\%s"} and \term{"\%D"} pattern
-  variables in Filter: \term{"\%u"} is replaced by a user's part of a JID,
-  \term{"\%d"} is replaced by the corresponding domain (virtual host),
-  all \term{"\%s"} variables are consecutively replaced by values of FilterAttrs
-  attributes and \term{"\%D"} is replaced by Distinguished Name. By default
-  \term{ldap\_dn\_filter} is undefined.
-  Example:
-\begin{verbatim}
-ldap_dn_filter:
-  "(&(name=%s)(owner=%D)(user=%u@%d))": ["sn"]
-\end{verbatim}
-  Since this filter makes additional LDAP lookups, use it only in the
-  last resort: try to define all filter rules in \term{ldap\_filter} if possible.
-  \titem{\{ldap\_local\_filter, Filter\}}\ind{options!ldap\_local\_filter}
-  If you can't use \term{ldap\_filter} due to performance reasons
-  (the LDAP server has many users registered),
-  you can use this local filter.
-  The local filter checks an attribute in ejabberd,
-  not in LDAP, so this limits the load on the LDAP directory.
-  The default filter is: \term{undefined}.
-  Example values:
-\begin{verbatim}
-{ldap_local_filter, {notequal, {"accountStatus",["disabled"]}}}.
-{ldap_local_filter, {equal, {"accountStatus",["enabled"]}}}.
-{ldap_local_filter, undefined}.
-\end{verbatim}
-
-\end{description}
-
-\makesubsubsection{ldapexamples}{Examples}
-
-\makeparagraph{ldapcommonexample}{Common example}
-
-Let's say \term{ldap.example.org} is the name of our LDAP server. We have
-users with their passwords in \term{"ou=Users,dc=example,dc=org"} directory.
-Also we have addressbook, which contains users emails and their additional
-infos in \term{"ou=AddressBook,dc=example,dc=org"} directory.
-The connection to the LDAP server is encrypted using TLS,
-and using the custom port 6123.
-Corresponding authentication section should looks like this:
-
-\begin{verbatim}
-## Authentication method
-auth_method: [ldap]
-## DNS name of our LDAP server
-ldap_servers: ["ldap.example.org"]
-## Bind to LDAP server as "cn=Manager,dc=example,dc=org" with password "secret"
-ldap_rootdn: "cn=Manager,dc=example,dc=org"
-ldap_password: "secret"
-ldap_encrypt: tls
-ldap_port: 6123
-## Define the user's base
-ldap_base: "ou=Users,dc=example,dc=org"
-## We want to authorize users from 'shadowAccount' object class only
-ldap_filter: "(objectClass=shadowAccount)"
-\end{verbatim}
-
-Now we want to use users LDAP-info as their vCards.  We have four attributes
-defined in our LDAP schema: \term{"mail"} --- email address, \term{"givenName"}
---- first name, \term{"sn"} --- second name, \term{"birthDay"} --- birthday.
-Also we want users to search each other.  Let's see how we can set it up:
-
-\begin{verbatim}
-modules:
-  ...
-  mod_vcard_ldap:
-    ## We use the same server and port, but want to bind anonymously because
-    ## our LDAP server accepts anonymous requests to
-    ## "ou=AddressBook,dc=example,dc=org" subtree.
-    ldap_rootdn: ""
-    ldap_password: ""
-    ## define the addressbook's base
-    ldap_base: "ou=AddressBook,dc=example,dc=org"
-    ## uidattr: user's part of JID is located in the "mail" attribute
-    ## uidattr_format: common format for our emails
-    ldap_uids:
-      "mail": "%u@mail.example.org"
-    ## We have to define empty filter here, because entries in addressbook does not
-    ## belong to shadowAccount object class
-    ldap_filter: ""
-    ## Now we want to define vCard pattern
-    ldap_vcard_map:
-     "NICKNAME": {"%u": []} # just use user's part of JID as his nickname
-     "GIVEN": {"%s": ["givenName"]}
-     "FAMILY": {"%s": ["sn"]}
-     "FN": {"%s, %s": ["sn", "givenName"]}, # example: "Smith, John"
-     "EMAIL": {"%s": ["mail"]}
-     "BDAY": {"%s": ["birthDay"]}]}
-    ## Search form
-    ldap_search_fields:
-      "User": "%u"
-      "Name": "givenName"
-      "Family Name": "sn"
-      "Email": "mail"
-      "Birthday": "birthDay"
-    ## vCard fields to be reported
-    ## Note that JID is always returned with search results
-    ldap_search_reported:
-      "Full Name": "FN"
-      "Nickname": "NICKNAME"
-      "Birthday": "BDAY"
-  ...
-\end{verbatim}
-
-Note that \modvcardldap{} module checks for the existence of the user before
-searching in his information in LDAP.
-
-
-\makeparagraph{ad}{Active Directory}
-\ind{databases!Active Directory}
-
-Active Directory is just an LDAP-server with predefined attributes. A sample
-configuration is shown below:
-
-\begin{verbatim}
-auth_method: [ldap]
-ldap_servers: ["office.org"]  # List of LDAP servers
-ldap_base: "DC=office,DC=org" # Search base of LDAP directory
-ldap_rootdn: "CN=Administrator,CN=Users,DC=office,DC=org" # LDAP manager
-ldap_password: "*******" # Password to LDAP manager
-ldap_uids: ["sAMAccountName"]
-ldap_filter: "(memberOf=*)"
-
-modules: 
-  ...
-  mod_vcard_ldap: 
-    ldap_vcard_map: 
-      "NICKNAME": {"%u", []}
-      "GIVEN": {"%s", ["givenName"]}
-      "MIDDLE": {"%s", ["initials"]}
-      "FAMILY": {"%s", ["sn"]}
-      "FN": {"%s", ["displayName"]}
-      "EMAIL": {"%s", ["mail"]}
-      "ORGNAME": {"%s", ["company"]}
-      "ORGUNIT": {"%s", ["department"]}
-      "CTRY": {"%s", ["c"]}
-      "LOCALITY": {"%s", ["l"]}
-      "STREET": {"%s", ["streetAddress"]}
-      "REGION": {"%s", ["st"]}
-      "PCODE": {"%s", ["postalCode"]}
-      "TITLE": {"%s", ["title"]}
-      "URL": {"%s", ["wWWHomePage"]}
-      "DESC": {"%s", ["description"]}
-      "TEL": {"%s", ["telephoneNumber"]}]}
-    ldap_search_fields: 
-      "User": "%u"
-      "Name": "givenName"
-      "Family Name": "sn"
-      "Email": "mail"
-      "Company": "company"
-      "Department": "department"
-      "Role": "title"
-      "Description": "description"
-      "Phone": "telephoneNumber"
-    ldap_search_reported: 
-      "Full Name": "FN"
-      "Nickname": "NICKNAME"
-      "Email": "EMAIL"
-  ...
-\end{verbatim}
-
-\makesubsection{riak}{Riak}
-\ind{databases!Riak}
-
-\footahref{http://basho.com/riak/}{Riak} is a distributed NoSQL key-value data store.
-The actual database access is defined in the options with \term{riak\_} prefix.
-
-\makesubsubsection{riakconnection}{Connection}
-\ind{riak!connection}
-
-The following paramaters are available:
-\begin{description}
-  \titem{riak\_server: String} A hostname of the Riak server. The default is
-  \term{``localhost''}.
-  \titem{riak\_port: Port} The port where the Riak server is accepting connections.
-  The defalt is 8087.
-  \titem{riak\_pool\_size: N} By default \ejabberd{} opens 10 connections to
-  the Riak server. You can change this number by using this option.
-  \titem{riak\_start\_interval: N} If the connection to the Riak server fails,
-  \ejabberd{} waits 30 seconds before retrying.
-  You can modify this interval with this option.
-\end{description}
-
-Example configuration:
-\begin{verbatim}
-riak_server: "riak.server.com"
-riak_port: 9097
-\end{verbatim}
-
-\makesubsubsection{riakstorage}{Storage}
-\ind{riak!storage}
-
-Several \ejabberd{} modules can be used to store information in Riak database.
-Refer to the corresponding module documentation to see if it supports such
-ability. To enable storage to Riak database, just make
-sure that your database is running well (see the next section), and add the
-module option \term{db\_type: riak}.
-
-\makesubsubsection{riakconfiguration}{Riak Configuration}
-\ind{riak!configuration}
-
-First, you need to configure Riak to use
-\footahref{http://en.wikipedia.org/wiki/LevelDB}{LevelDB} as a database backend.
-
-If you are using Riak 2.x and higher, configure \term{storage\_backend} option
-of \term{/etc/riak/riak.conf} as follows:
-\begin{verbatim}
-...
-storage_backend = leveldb
-...
-\end{verbatim}
-
-If you are using Riak 1.4.x and older, configure \term{storage\_backend} option
-of \term{/etc/riak/app.config} in the section \term{riak\_kv} as follows:
-\begin{verbatim}
-...
- {riak_kv, [
-            ...
-            {storage_backend, riak_kv_eleveldb_backend},
-...
-\end{verbatim}
-
-Second, Riak should be pointed to \ejabberd{} Erlang binary files (*.beam).
-As described in \ref{install}, by default those are located
-in \term{/lib/ejabberd/ebin} directory. So you
-should add the following to \term{/etc/riak/vm.args}:
-\begin{verbatim}
-...
-## Path to ejabberd beams in order to make map/reduce
--pz /lib/ejabberd/ebin
-...
-\end{verbatim}
-Important notice: make sure Riak has at least read access to that directory.
-Otherwise its startup will likely fail.
-
-\makesection{modules}{Modules Configuration}
-\ind{modules}
-
-The option \term{modules} defines the list of modules that will be loaded after
-\ejabberd{}'s startup. Each entry in the list is a tuple in which the first
-element is the name of a module and the second is a list of options for that
-module.
-
-The syntax is:
-\esyntax{modules: \{ ModuleName: ModuleOptions \}}
-
-Examples:
-\begin{itemize}
-\item In this example only the module \modecho{} is loaded and no module
-  options are specified between the square brackets:
-\begin{verbatim}
-modules:
-  mod_echo: {}
-\end{verbatim}
-\item In the second example the modules \modecho{}, \modtime{}, and
-  \modversion{} are loaded without options.
-\begin{verbatim}
-modules:
-  mod_echo:      {}
-  mod_time:      {}
-  mod_version:   {}
-\end{verbatim}
-\end{itemize}
-
-\makesubsection{modoverview}{Modules Overview}
-\ind{modules!overview}\ind{XMPP compliancy}
-
-The following table lists all modules included in \ejabberd{}.
-
-\begin{table}[H]
-  \centering
-  \begin{tabular}{|l|l|l|}
-    \hline {\bf Module} & {\bf Feature} & {\bf Dependencies} \\
-    \hline
-    \hline \modadhoc{} & Ad-Hoc Commands (\xepref{0050}) &  \\
-    \hline \ahrefloc{modannounce}{\modannounce{}} & Manage announcements & recommends \modadhoc{} \\
-    \hline \modblocking{} & Simple Communications Blocking (\xepref{0191}) & \modprivacy{} \\
-    \hline \modcaps{} &  Entity Capabilities (\xepref{0115}) & \\
-    \hline \modcarboncopy{} & Message Carbons (\xepref{0280}) & \\
-    \hline \ahrefloc{modclientstate}{\modclientstate{}} & Filter stanzas for inactive clients &  \\
-    \hline \modconfigure{} & Server configuration using Ad-Hoc & \modadhoc{} \\
-    \hline \ahrefloc{moddisco}{\moddisco{}} & Service Discovery (\xepref{0030}) &  \\
-    \hline \ahrefloc{modecho}{\modecho{}} & Echoes XMPP stanzas &  \\
-    \hline \ahrefloc{modfail2ban}{\modfailban{}} & Bans IPs that show the malicious signs & \\
-    \hline \ahrefloc{modhttpbind}{\modhttpbind{}} & XMPP over Bosh service (HTTP Binding) &  \\
-    \hline \ahrefloc{modhttpfileserver}{\modhttpfileserver{}} & Small HTTP file server &  \\
-    \hline \ahrefloc{modirc}{\modirc{}} & IRC transport &  \\
-    \hline \ahrefloc{modlast}{\modlast{}} & Last Activity (\xepref{0012}) &  \\
-    \hline \ahrefloc{modmuc}{\modmuc{}} & Multi-User Chat (\xepref{0045}) &  \\
-    \hline \ahrefloc{modmuclog}{\modmuclog{}} & Multi-User Chat room logging & \modmuc{} \\
-    \hline \ahrefloc{modoffline}{\modoffline{}} & Offline message storage (\xepref{0160}) &  \\
-    \hline \ahrefloc{modping}{\modping{}} & XMPP Ping and periodic keepalives (\xepref{0199}) &  \\
-    \hline \ahrefloc{modprescounter}{\modprescounter{}} & Detect presence subscription flood &  \\
-    \hline \ahrefloc{modprivacy}{\modprivacy{}} & Blocking Communication (\xepref{0016}) &  \\
-    \hline \ahrefloc{modprivate}{\modprivate{}} & Private XML Storage (\xepref{0049}) &  \\
-    \hline \ahrefloc{modproxy}{\modproxy{}} & SOCKS5 Bytestreams (\xepref{0065}) &  \\
-    \hline \ahrefloc{modpubsub}{\modpubsub{}} & Pub-Sub (\xepref{0060}), PEP (\xepref{0163}) & \modcaps{} \\
-    \hline \ahrefloc{modpubsub}{\modpubsubodbc{}} & Pub-Sub (\xepref{0060}), PEP (\xepref{0163}) & supported DB (*) and \modcaps{} \\
-    \hline \ahrefloc{modregister}{\modregister{}} & In-Band Registration (\xepref{0077}) &  \\
-    \hline \ahrefloc{modregisterweb}{\modregisterweb{}} & Web for Account Registrations &  \\
-    \hline \ahrefloc{modroster}{\modroster{}} & Roster management (XMPP IM) &  \\
-    \hline \ahrefloc{modservicelog}{\modservicelog{}} & Copy user messages to logger service &  \\
-    \hline \ahrefloc{modsharedroster}{\modsharedroster{}} & Shared roster management & \modroster{} \\
-    \hline \ahrefloc{modsharedrosterldap}{\modsharedrosterldap{}} & LDAP Shared roster management & \modroster{} \\
-    \hline \ahrefloc{modsic}{\modsic{}} & Server IP Check (\xepref{0279}) &  \\
-    \hline \ahrefloc{modsip}{\modsip{}} & SIP Registrar/Proxy (\footahref{http://tools.ietf.org/html/rfc3261}{RFC 3261}) & \term{ejabberd\_sip} \\
-    \hline \ahrefloc{modstats}{\modstats{}} & Statistics Gathering (\xepref{0039}) &  \\
-    \hline \ahrefloc{modtime}{\modtime{}} & Entity Time (\xepref{0202}) &  \\
-    \hline \ahrefloc{modvcard}{\modvcard{}} & vcard-temp (\xepref{0054}) &  \\
-    \hline \ahrefloc{modvcardldap}{\modvcardldap{}} & vcard-temp (\xepref{0054}) & LDAP server \\
-    \hline \ahrefloc{modvcardxupdate}{\modvcardxupdate{}} & vCard-Based Avatars (\xepref{0153}) & \modvcard{} \\
-    \hline \ahrefloc{modversion}{\modversion{}} & Software Version (\xepref{0092}) &  \\
-    \hline
-  \end{tabular}
-\end{table}
-
-\begin{itemize}
-\item (*) This module requires a supported database. For a list of supported databases, see section~\ref{database}.
-\end{itemize}
-
-You can see which database backend each module needs by looking at the suffix:
-\begin{itemize}
-\item No suffix, this means that the module uses Erlang's built-in database
-  Mnesia as backend, Riak key-value store or ODBC database (see~\ref{database}).
-\item `\_ldap', this means that the module needs an LDAP server as backend.
-\end{itemize}
-
-You can find more
-\footahref{http://www.ejabberd.im/contributions}{contributed modules} on the
-\ejabberd{} website. Please remember that these contributions might not work or
-that they can contain severe bugs and security leaks. Therefore, use them at
-your own risk!
-
-
-\makesubsection{modcommonoptions}{Common Options}
-
-The following options are used by many modules. Therefore, they are described in
-this separate section.
-
-\makesubsubsection{modiqdiscoption}{\option{iqdisc}}
-\ind{options!iqdisc}
-
-Many modules define handlers for processing IQ queries of different namespaces
-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.
-
-The syntax is:
-\esyntax{iqdisc: Value}
-
-Possible \term{Value} are:
-\begin{description}
-\titem{no\_queue} All queries of a namespace with this processing discipline are
-  processed directly. This means that the XMPP connection that sends this IQ query gets blocked:
-  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{N} N separate queues are created to process the
-  queries. The queries are thus processed in parallel, but in a
-  controlled way.
-\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:
-\begin{verbatim}
-modules:
-  ...
-  mod_time:
-    iqdisc: no_queue
-  ...
-\end{verbatim}
-
-\makesubsubsection{modhostoption}{\option{host}}
-\ind{options!host}
-
-This option defines the Jabber ID of a service provided by an \ejabberd{} module.
-
-The syntax is:
-\esyntax{host: HostName}
-
-If you include the keyword "@HOST@" in the HostName,
-it is replaced at start time with the real virtual host string.
-
-This example configures
-the \ind{modules!\modecho{}}echo module to provide its echoing service
-in the Jabber ID \jid{mirror.example.org}:
-\begin{verbatim}
-modules:
-  ...
-  mod_echo:
-    host: "mirror.example.org"
-  ...
-\end{verbatim}
-
-However, if there are several virtual hosts and this module is enabled in all of them,
-the "@HOST@" keyword must be used:
-\begin{verbatim}
-modules:
-  ...
-  mod_echo:
-    host: "mirror.@HOST@"
-  ...
-\end{verbatim}
-
-\makesubsection{modannounce}{\modannounce{}}
-\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 perform these actions with a
-\XMPP{} client either using Ad-hoc commands
-or sending messages to specific JIDs.
-
-The Ad-hoc commands are listed in the Server Discovery.
-For this feature to work, \modadhoc{} must be enabled.
-
-The specific JIDs where messages can be sent are listed bellow.
-The first JID in each entry will apply only to the specified virtual host
-\jid{example.org}, while the JID between brackets will apply to all virtual
-hosts in ejabberd.
-\begin{description}
-\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{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}
-\dbtype
-\titem{access: AccessName} \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}
-
-Examples:
-\begin{itemize}
-\item Only administrators can send announcements:
-\begin{verbatim}
-access:
-  announce:
-    admin: allow
-
-modules:
-  ...
-  mod_adhoc: {}
-  mod_announce:
-    access: announce
-  ...
-\end{verbatim}
-\item Administrators as well as the direction can send announcements:
-\begin{verbatim}
-acl:
-  direction:
-    user:
-      "big_boss": "example.org"
-      "assistant": "example.org"
-  admin:
-    user:
-      "admin": "example.org"
-access:
-  announce:
-    admin: allow
-    direction: allow
-
-modules:
-  ...
-  mod_adhoc: {}
-  mod_announce:
-    access: announce
-  ...
-\end{verbatim}
-\end{itemize}
-
-Note that \modannounce{} can be resource intensive on large
-deployments as it can broadcast lot of messages. This module should be
-disabled for instances of \ejabberd{} with hundreds of thousands users.
-
-\makesubsection{modclientstate}{\modclientstate{}}
-\ind{modules!\modclientstate{}}\ind{Client State Indication}
-\ind{protocols!XEP-0352: Client State Indication}
-
-This module allows for queueing or dropping certain types of stanzas
-when a client indicates that the user is not actively using the client
-at the moment (see \xepref{0352}). This can save bandwidth and
-resources.
-
-Options:
-\begin{description}
-\titem{drop\_chat\_states: true|false} \ind{options!drop\_chat\_states}
-  Drop most "standalone" Chat State Notifications (as defined in
-  \xepref{0085}) while a client indicates inactivity. The default value
-  is \term{false}.
-\titem{queue\_presence: true|false} \ind{options!queue\_presence}
-  While a client is inactive, queue presence stanzas that indicate
-  (un)availability. The latest queued stanza of each contact is
-  delivered as soon as the client becomes active again. The default
-  value is \term{false}.
-\end{description}
-
-Example:
-\begin{verbatim}
-modules:
-  ...
-  mod_client_state:
-    drop_chat_states: true
-    queue_presence: true
-  ...
-\end{verbatim}
-
-\makesubsection{moddisco}{\moddisco{}}
-\ind{modules!\moddisco{}}
-\ind{protocols!XEP-0030: Service Discovery}
-\ind{protocols!XEP-0011: Jabber Browsing}
-\ind{protocols!XEP-0094: Agent Information}
-\ind{protocols!XEP-0157: Contact Addresses for XMPP Services}
-
-This module adds support for Service Discovery (\xepref{0030}). With
-this module enabled, services on your server can be discovered by
-\XMPP{} clients. Note that \ejabberd{} has no modules with support
-for the superseded Jabber Browsing (\xepref{0011}) and Agent Information
-(\xepref{0094}). Accordingly, \XMPP{} 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{Service Discovery (\ns{http://jabber.org/protocol/disco\#items} and
-  \ns{http://jabber.org/protocol/disco\#info})}
-\titem{extra\_domains: [Domain, ...]} \ind{options!extra\_domains}With this option,
-  you can specify a list of extra domains that are added to the Service Discovery item list.
-\titem{server\_info: [ \{ modules: Modules, name: Name, urls: [URL, ...] \} ]} \ind{options!server\_info}
-  Specify additional information about the server,
-  as described in Contact Addresses for XMPP Services (\xepref{0157}).
-  \term{Modules} can be the keyword `all', 
-  in which case the information is reported in all the services;
-  or a list of \ejabberd{} modules, 
-  in which case the information is only specified for the services provided by those modules.
-  Any arbitrary \term{Name} and \term{URL} can be specified, not only contact addresses.
-\end{description}
-
-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:
-      - "example.org"
-      - "example.com"
-  ...
-\end{verbatim}
-\item With this configuration, all services show abuse addresses,
-feedback address on the main server,
-and admin addresses for both the main server and the vJUD service:
-\begin{verbatim}
-modules:
-  ...
-  mod_disco:
-    server_info:
-      - 
-        modules: all
-        name: "abuse-addresses"
-        urls: ["mailto:abuse@shakespeare.lit"]
-      - 
-        modules: [mod_muc]
-        name: "Web chatroom logs"
-        urls: ["http://www.example.org/muc-logs"]
-      - 
-        modules: [mod_disco]
-        name: "feedback-addresses"
-        urls:
-          - "http://shakespeare.lit/feedback.php"
-          - "mailto:feedback@shakespeare.lit"
-          - "xmpp:feedback@shakespeare.lit"
-      - 
-        modules:
-          - mod_disco
-          - mod_vcard
-        name: "admin-addresses"
-        urls:
-          - "mailto:xmpp@shakespeare.lit"
-          - "xmpp:admins@shakespeare.lit"
-  ...
-\end{verbatim}
-\end{itemize}
-
-\makesubsection{modecho}{\modecho{}}
-\ind{modules!\modecho{}}\ind{debugging}
-
-This module simply echoes any \XMPP{}
-packet back to the sender. This mirror can be of interest for
-\ejabberd{} and \XMPP{} client debugging.
-
-Options:
-\begin{description}
-\hostitem{echo}
-\end{description}
-
-Example: Mirror, mirror, on the wall, who is the most beautiful
-  of them all?
-\begin{verbatim}
-modules:
-  ...
-  mod_echo:
-    host: "mirror.example.org"
-  ...
-\end{verbatim}
-
-\makesubsection{modfail2ban}{\modfailban{}}
-\ind{modules!\modfailban{}}\ind{modfail2ban}
-
-The module bans IPs that show the malicious signs. Currently only C2S authentication
-failures are detected.
-
-Available options:
-\begin{description}
-  \titem{c2s\_auth\_ban\_lifetime: Seconds} The lifetime of the IP ban caused by too
-  many C2S authentication failures. The default is 3600, i.e. one hour.
-  \titem{c2s\_max\_auth\_failures: Integer} The number of C2S authentication failures to
-  trigger the IP ban. The default is 20.
-\end{description}
-
-Example:
-\begin{verbatim}
-modules:
-  ...
-  mod_fail2ban:
-    c2s_auth_block_lifetime: 7200
-    c2s_max_auth_failures: 50
-  ...
-\end{verbatim}
-
-\makesubsection{modhttpbind}{\modhttpbind{}}
-\ind{modules!\modhttpbind{}}\ind{modhttpbind}
-
-This module implements XMPP over Bosh (formerly known as HTTP Binding)
-as defined in \xepref{0124} and \xepref{0206}.
-It extends ejabberd's built in HTTP service with a configurable
-resource at which this service will be hosted.
-
-To use HTTP-Binding, enable the module:
-\begin{verbatim}
-modules:
-  ...
-  mod_http_bind: {}
-  ...
-\end{verbatim}
-and add \verb|http_bind| in the HTTP service. For example:
-\begin{verbatim}
-listen:
-  ...
-  - 
-    port: 5280
-    module: ejabberd_http
-    http_bind: true
-    http_poll: true
-    web_admin: true
-  ...
-\end{verbatim}
-With this configuration, the module will serve the requests sent to 
-\verb|http://example.org:5280/http-bind/|
-Remember that this page is not designed to be used by web browsers,
-it is used by XMPP clients that support XMPP over Bosh.
-
-If you want to set the service in a different URI path or use a different module, 
-you can configure it manually using the option \verb|request_handlers|. 
-For example:
-\begin{verbatim}
-listen:
-  ...
-  - 
-    port: 5280
-    module: ejabberd_http
-    request_handlers:
-       "/http-bind": mod_http_bind
-    http_poll: true
-    web_admin: true
-  ...
-\end{verbatim}
-
-Options:
-\begin{description}
-  \titem{\{max\_inactivity, Seconds\}} \ind{options!max\_inactivity}
-  Define the maximum inactivity period in seconds.
-  Default value is 30 seconds.
-  For example, to set 50 seconds:
-\begin{verbatim}
-modules:
-  ...
-  mod_http_bind:
-    max_inactivity: 50
-  ...
-\end{verbatim}
-\end{description}
-
-
-\makesubsection{modhttpfileserver}{\modhttpfileserver{}}
-\ind{modules!\modhttpfileserver{}}\ind{modhttpfileserver}
-
-This simple module serves files from the local disk over HTTP.
-
-Options:
-\begin{description}
-  \titem{docroot: Path} \ind{options!docroot}
-    Directory to serve the files.
-  \titem{accesslog: Path} \ind{options!accesslog}
-    File to log accesses using an Apache-like format.
-    No log will be recorded if this option is not specified.
-  \titem{directory\_indices: [Index, ...]} \ind{options!directoryindices}
-    Indicate one or more directory index files, similarly to Apache's
-    DirectoryIndex variable. When a web request hits a directory
-    instead of a regular file, those directory indices are looked in
-    order, and the first one found is returned.
-  \titem{custom\_headers: \{Name: Value\}} \ind{options!customheaders}
-    Indicate custom HTTP headers to be included in all responses.
-    Default value is: \term{[]}
-  \titem{content\_types: \{Name: Type\}} \ind{options!contenttypes}
-    Specify mappings of extension to content type.
-    There are several content types already defined,
-    with this option you can add new definitions, modify or delete existing ones.
-    To delete an existing definition, simply define it with a value: `undefined'.
-  \titem{default\_content\_type: Type} \ind{options!defaultcontenttype}
-    Specify the content type to use for unknown extensions.
-    Default value is `application/octet-stream'.
-\end{description}
-
-This example configuration will serve the files from 
-the local directory \verb|/var/www|
-in the address \verb|http://example.org:5280/pub/archive/|.
-In this example a new content type \term{ogg} is defined,
-\term{png} is redefined, and \term{jpg} definition is deleted.
-To use this module you must enable it:
-\begin{verbatim}
-modules:
-  ...
-  mod_http_fileserver:
-    docroot: "/var/www"
-    accesslog: "/var/log/ejabberd/access.log"
-    directory_indices:
-      - "index.html"
-      - "main.htm"
-    custom_headers:
-      "X-Powered-By": "Erlang/OTP"
-      "X-Fry": "It's a widely-believed fact!"
-    content_types:
-      ".ogg": "audio/ogg"
-      ".png": "image/png"
-      ".jpg": undefined
-    default_content_type: "text/html"
-  ...
-\end{verbatim}
-And define it as a handler in the HTTP service:
-\begin{verbatim}
-listen:
-  ...
-  - 
-    port: 5280
-    module: ejabberd_http
-    request_handlers:
-      ...
-      "/pub/archive": mod_http_fileserver
-      ...
-  ...
-\end{verbatim}
-
-\makesubsection{modirc}{\modirc{}}
-\ind{modules!\modirc{}}\ind{IRC}
-
-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!XEP-0045: Multi-User Chat}
-\begin{itemize}
-\item A \XMPP{} client with `groupchat 1.0' support or Multi-User
-  Chat support (\xepref{0045}) is necessary to join IRC channels.
-\item An IRC channel can be joined in nearly the same way as joining a
-  \XMPP{} 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 The IRC transport provides Ad-Hoc Commands (\xepref{0050})
-  to join a channel, and to set custom IRC username and encoding.
-\item When using a popular \XMPP{} server, it can occur that no
-  connection can be achieved with some IRC servers because they limit the
-  number of connections from one IP.
-\end{itemize}
-
-Options:
-\begin{description}
-\hostitem{irc}
-\dbtype
-\titem{access: AccessName} \ind{options!access}This option can be used to specify who
-  may use the IRC transport (default value: \term{all}).
-\titem{default\_encoding: Encoding} \ind{options!defaultencoding}Set the default IRC encoding.
-  Default value: \term{"iso8859-1"}
-\end{description}
-
-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. The default encoding is set to "iso8859-15".
-\begin{verbatim}
-modules:
-  ...
-  mod_irc:
-    access: all
-    default_encoding: "iso8859-15"
-  ...
-\end{verbatim}
-\item In next example the IRC transport is available with JIDs with prefix \jid{irc-t.net}.
-  Moreover, the transport is only accessible to two users 
-  of \term{example.org}, and any user of \term{example.com}:
-\begin{verbatim}
-acl:
-  paying_customers:
-    user:
-      - "customer1": "example.org"
-      - "customer2": "example.org"
-    server: "example.com"
-
-access:
-  irc_users:
-    paying_customers: allow
-    all: deny
-
-modules:
-  ...
-  mod_irc:
-    access: irc_users
-    host: "irc.example.net"
-  ...
-\end{verbatim}
-\end{itemize}
-
-\makesubsection{modlast}{\modlast{}}
-\ind{modules!\modlast{}}\ind{protocols!XEP-0012: Last Activity}
-
-This module adds support for Last Activity (\xepref{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{Last activity (\ns{jabber:iq:last})}
-\dbtype
-\end{description}
-
-\makesubsection{modmuc}{\modmuc{}}
-\ind{modules!\modmuc{}}\ind{protocols!XEP-0045: Multi-User Chat}\ind{conferencing}
-
-This module provides a Multi-User Chat (\xepref{0045}) service.
-Users can discover existing rooms, join or create them.
-Occupants of a room can chat in public or have private chats.
-
-Some of the features of Multi-User Chat:
-\begin{itemize}
-\item Sending public and private messages to room occupants.
-\item Inviting other users to a room.
-\item Setting a room subject.
-\item Creating password protected rooms.
-\item Kicking and banning occupants.
-\end{itemize}
-
-The MUC service allows any Jabber ID to register a nickname,
-so nobody else can use that nickname in any room in the MUC service.
-To register a nickname, open the Service Discovery in your
-XMPP client and register in the MUC service.
-
-This module supports clustering and load
-balancing. One module can be started per cluster node. Rooms are
-distributed at creation time on all available MUC module
-instances. The multi-user chat module is clustered but the rooms
-themselves are not clustered nor fault-tolerant: if the node managing a
-set of rooms goes down, the rooms disappear and they will be recreated
-on an available node on first connection attempt.
-
-Module options:
-\begin{description}
-\hostitem{conference}
-\dbtype
-\titem{access: AccessName} \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: AccessName} \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 any account in the local ejabberd server is allowed to create rooms.
-\titem{access\_persistent: AccessName} \ind{options!access\_persistent}To configure who is
-  allowed to modify the 'persistent' room option.
-  By default any account in the local ejabberd server is allowed to modify that option.
-\titem{access\_admin: AccessName} \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.
-  The administrators can send a normal message to the service JID,
-  and it will be shown in all active rooms as a service message.
-  The administrators can send a groupchat message to the JID of an active room,
-  and the message will be shown in the room as a service message.
-\titem{history\_size: Size} \ind{options!history\_size}A small history of
-  the current discussion is sent to users when they enter the
-  room. With this option you can define the number of history messages
-  to keep and send to users joining the room. The value is an
-  integer. Setting the value to \term{0} disables the history feature
-  and, as a result, nothing is kept in memory. The default value is
-  \term{20}. This value is global and thus affects all rooms on the
-  service.
-\titem{max\_users: Number} \ind{options!max\_users} This option defines at
-  the service level, the maximum number of users allowed per
-  room. It can be lowered in each room configuration but cannot be
-  increased in individual room configuration. The default value is
-  200.
-\titem{max\_users\_admin\_threshold: Number}
-  \ind{options!max\_users\_admin\_threshold} This option defines the
-  number of service admins or room owners allowed to enter the room when
-  the maximum number of allowed occupants was reached. The default limit
-  is 5.
-\titem{max\_user\_conferences: Number}
-  \ind{options!max\_user\_conferences} This option defines the maximum
-  number of rooms that any given user can join. The default value
-  is 10. This option is used to prevent possible abuses. Note that
-  this is a soft limit: some users can sometimes join more conferences
-  in cluster configurations.
-\titem{max\_room\_id: Number} \ind{options!max\_room\_id}
-  This option defines the maximum number of characters that Room ID
-  can have when creating a new room.
-  The default value is to not limit: \term{infinity}.
-\titem{max\_room\_name: Number} \ind{options!max\_room\_name}
-  This option defines the maximum number of characters that Room Name
-  can have when configuring the room.
-  The default value is to not limit: \term{infinity}.
-\titem{max\_room\_desc: Number} \ind{options!max\_room\_desc}
-  This option defines the maximum number of characters that Room Description
-  can have when configuring the room.
-  The default value is to not limit: \term{infinity}.
-\titem{min\_message\_interval: Number} \ind{options!min\_message\_interval}
-  This option defines the minimum interval between two messages send
-  by an occupant in seconds. This option is global and valid for all
-  rooms. A decimal value can be used. When this option is not defined,
-  message rate is not limited. This feature can be used to protect a
-  MUC service from occupant abuses and limit number of messages that will
-  be broadcasted by the service. A good value for this minimum message
-  interval is 0.4 second. If an occupant tries to send messages faster, an
-  error is send back explaining that the message has been discarded
-  and describing the reason why the message is not acceptable.
-\titem{min\_presence\_interval: Number}
-  \ind{options!min\_presence\_interval} This option defines the
-  minimum of time between presence changes coming from a given occupant in
-  seconds. This option is global and valid for all rooms. A
-  decimal value can be used. When this option is not defined, no
-  restriction is applied. This option can be used to protect a MUC
-  service for occupants abuses. If an occupant tries
-  to change its presence more often than the specified interval, the
-  presence is cached by \ejabberd{} and only the last presence is
-  broadcasted to all occupants in the room after expiration of the
-  interval delay. Intermediate presence packets are silently
-  discarded. A good value for this option is 4 seconds.
-\titem{default\_room\_options: \{OptionName: OptionValue\}} \ind{options!default\_room\_options}
-  This module option allows to define the desired default room options.
-  Note that the creator of a room can modify the options of his room
-  at any time using an XMPP client with MUC capability.
-  The available room options and the default values are:
-  \begin{description}
-  \titem{allow\_change\_subj: true|false} Allow occupants to change the subject.
-  \titem{allow\_private\_messages: true|false} Occupants can send private messages to other occupants.
-  \titem{allow\_private\_messages\_from\_visitors: anyone|moderators|nobody} Visitors can send private messages to other occupants.
-  \titem{allow\_query\_users: true|false} Occupants can send IQ queries to other occupants.
-  \titem{allow\_user\_invites: false|true} Allow occupants to send invitations.
-  \titem{allow\_visitor\_nickchange: true|false} Allow visitors to
-  change nickname.
-  \titem{allow\_visitor\_status: true|false} Allow visitors to send
-  status text in presence updates.  If disallowed, the \term{status}
-  text is stripped before broadcasting the presence update to all
-  the room occupants.
-  \titem{anonymous: true|false} The room is anonymous:
-  occupants don't see the real JIDs of other occupants.
-  Note that the room moderators can always see the real JIDs of the occupants.
-  \titem{captcha\_protected: false} 
-  When a user tries to join a room where he has no affiliation (not owner, admin or member),
-  the room requires him to fill a CAPTCHA challenge (see section \ref{captcha})
-  in order to accept her join in the room.
-  \titem{logging: false|true} The public messages are logged using \term{mod\_muc\_log}.
-  \titem{max\_users: 200} Maximum number of occupants in the room.
-  \titem{members\_by\_default: true|false} The occupants that enter the room are participants by default, so they have 'voice'.
-  \titem{members\_only: false|true} Only members of the room can enter.
-  \titem{moderated: true|false} Only occupants with 'voice' can send public messages.
-  \titem{password: "roompass123"} Password of the room. You may want to enable the next option too.
-  \titem{password\_protected: false|true} The password is required to enter the room.
-  \titem{persistent: false|true} The room persists even if the last participant leaves.
-  \titem{public: true|false} The room is public in the list of the MUC service, so it can be discovered.
-  \titem{public\_list: true|false} The list of participants is public, without requiring to enter the room.
-  \titem{title: "Room Title"} A human-readable title of the room.
-  \end{description}
-  All of those room options can be set to \term{true} or \term{false},
-  except \term{password} and \term{title} which are strings,
-  and \term{max\_users} that is integer.
-\end{description}
-
-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. When \jid{admin@example.org}
-  sends a message such as `Tomorrow, the \XMPP{} server will be moved
-  to new hardware. This will involve service breakdowns around 23:00 UMT.
-  We apologise for this inconvenience.' to \jid{conference.example.org},
-  it will be displayed in all active rooms. In this example the history
-  feature is disabled.
-\begin{verbatim}
-acl:
-  admin:
-    user:
-      - "admin": "example.org"
-
-access:
-  muc_admin:
-    admin: allow
-
-modules:
-  ...
-  mod_muc:
-    access: all
-    access_create: all
-    access_admin: muc_admin
-    history_size: 0
-  ...
-\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. When
-  \jid{admin@example.org} sends a message such as `Tomorrow, the \Jabber{}
-  server will be moved to new hardware. This will involve service breakdowns
-  around 23:00 UMT. We apologise for this inconvenience.' to
-  \jid{conference.example.org}, it will be displayed in all active rooms. No
-  \term{history\_size} option is used, this means that the feature is enabled
-  and the default value of 20 history messages will be send to the users.
-\begin{verbatim}
-acl:
-  paying_customers:
-    user:
-      - "customer1": "example.net"
-      - "customer2": "example.com"
-      - "customer3": "example.org"
-  admin:
-    user:
-      - "admin": "example.org"
-
-access:
-  muc_admin
-    admin: allow
-    all: deny
-  muc_access:
-    paying_customers: allow
-    admin: allow
-    all: deny
-
-modules:
-  ...
-  mod_muc:
-    access: muc_access
-    access_create: muc_admin
-    access_admin: muc_admin
-  ...
-\end{verbatim}
-
-\item In the following example, MUC anti abuse options are used. An
-occupant cannot send more than one message every 0.4 seconds and cannot
-change its presence more than once every 4 seconds.
-The length of Room IDs and Room Names are limited to 20 characters,
-and Room Description to 300 characters. No ACLs are
-defined, but some user restriction could be added as well:
-
-\begin{verbatim}
-modules:
-  ...
-  mod_muc:
-    min_message_interval: 0.4
-    min_presence_interval: 4
-    max_room_id: 20
-    max_room_name: 20
-    max_room_desc: 300
-  ...
-\end{verbatim}
-
-\item This example shows how to use \option{default\_room\_options} to make sure
-  the newly created rooms have by default those options.
-\begin{verbatim}
-modules:
-  ...
-  mod_muc:
-    access: muc_access
-    access_create: muc_admin
-    default_room_options:
-      allow_change_subj: false
-      allow_query_users: true
-      allow_private_messages: true
-      members_by_default: false
-      title: "New chatroom"
-      anonymous: false
-    access_admin: muc_admin
-  ...
-\end{verbatim}
-\end{itemize}
-
-\makesubsection{modmuclog}{\modmuclog{}}
-\ind{modules!\modmuclog{}}
-
-This module enables optional logging of Multi-User Chat (MUC) public conversations to
-HTML. Once you enable this module, users can join a room using a MUC capable
-XMPP client, and if they have enough privileges, they can request the
-configuration form in which they can set the option to enable room logging.
-
-Features:
-\begin{itemize}
-\item Room details are added on top of each page: room title, JID,
-  author, subject and configuration.
-\item \ind{protocols!RFC 5122: Internationalized Resource Identifiers (IRIs) and Uniform Resource Identifiers (URIs) for the Extensible Messaging and Presence Protocol (XMPP)}
-  The room JID in the generated HTML is a link to join the room (using
-  \footahref{http://xmpp.org/rfcs/rfc5122.html}{XMPP URI}).
-\item Subject and room configuration changes are tracked and displayed.
-\item Joins, leaves, nick changes, kicks, bans and `/me' are tracked and
-  displayed, including the reason if available.
-\item Generated HTML files are XHTML 1.0 Transitional and CSS compliant.
-\item Timestamps are self-referencing links.
-\item Links on top for quicker navigation: Previous day, Next day, Up.
-\item CSS is used for style definition, and a custom CSS file can be used.
-\item URLs on messages and subjects are converted to hyperlinks.
-\item Timezone used on timestamps is shown on the log files.
-\item A custom link can be added on top of each page.
-\end{itemize}
-
-Options:
-\begin{description}
-\titem{access\_log: AccessName}\ind{options!access\_log}
-  This option restricts which occupants are allowed to enable or disable room
-  logging. The default value is \term{muc\_admin}. Note for this default setting
-  you need to have an access rule for \term{muc\_admin} in order to take effect.
-\titem{cssfile: false|URL}\ind{options!cssfile}
-  With this option you can set whether the HTML files should have a custom CSS
-  file or if they need to use the embedded CSS file. Allowed values are
-  \term{false} and an URL to a CSS file. With the first value, HTML files will
-  include the embedded CSS code. With the latter, you can specify the URL of the
-  custom CSS file (for example: \term{"http://example.com/my.css"}). The default value
-  is \term{false}.
-\titem{dirname: room\_jid|room\_name}\ind{options!dirname}
-  Allows to configure the name of the room directory.
-  Allowed values are \term{room\_jid} and \term{room\_name}.
-  With the first value, the room directory name will be the full room JID.
-  With the latter, the room directory name will be only the room name,
-  not including the MUC service name.
-  The default value is \term{room\_jid}.
-\titem{dirtype: subdirs|plain}\ind{options!dirtype}
-  The type of the created directories can be specified with this option. Allowed
-  values are \term{subdirs} and \term{plain}. With the first value,
-  subdirectories are created for each year and month. With the latter, the
-  names of the log files contain the full date, and there are no subdirectories.
-  The default value is \term{subdirs}.
-\titem{file\_format: html|plaintext}\ind{options!file\_format}
-  Define the format of the log files:
-  \term{html} stores in HTML format,
-  \term{plaintext} stores in plain text.
-  The default value is \term{html}.
-\titem{file\_permissions: \{mode: Mode, group: Group\}}\ind{options!file\_permissions}
-  Define the permissions that must be used when creating the log files:
-  the number of the mode, and the numeric id of the group that will own the files.
-  The default value is \term{\{644, 33\}}.
-\titem{outdir: Path}\ind{options!outdir}
-  This option sets the full path to the directory in which the HTML files should
-  be stored. Make sure the \ejabberd{} daemon user has write access on that
-  directory. The default value is \term{"www/muc"}.
-\titem{spam\_prevention: true|false}\ind{options!spam\_prevention}
-  To prevent spam, the \term{spam\_prevention} option adds a special attribute
-  to links that prevent their indexation by search engines. The default value
-  is \term{true}, which mean that nofollow attributes will be added to user
-  submitted links.
-\titem{timezone: local|universal}\ind{options!timezone}
-  The time zone for the logs is configurable with this option. Allowed values
-  are \term{local} and \term{universal}. With the first value, the local time,
-  as reported to Erlang by the operating system, will be used. With the latter,
-  GMT/UTC time will be used. The default value is \term{local}.
-\titem{top\_link: \{URL: Text\}}\ind{options!top\_link}
-  With this option you can customize the link on the top right corner of each
-  log file. The default value is \term{\{"/", "Home"\}}.
-\end{description}
-
-Examples:
-\begin{itemize}
-\item In the first example any room owner can enable logging, and a
-  custom CSS file will be used (http://example.com/my.css). The names
-  of the log files will contain the full date, and there will be no
-  subdirectories. The log files will be stored in /var/www/muclogs, and the
-  time zone will be GMT/UTC. Finally, the top link will be
-  \verb|<a href="http://www.jabber.ru/">Jabber.ru</a>|.
-\begin{verbatim}
-access: 
-  muc: 
-    all: allow
-
-modules: 
-  ...
-  mod_muc_log: 
-    access_log: muc
-    cssfile: "http://example.com/my.css"
-    dirtype: plain
-    dirname: room_jid
-    outdir: "/var/www/muclogs"
-    timezone: universal
-    spam_prevention: true
-    top_link: 
-      "http://www.jabber.ru/": "Jabber.ru"
-  ...
-\end{verbatim}
-  \item In the second example only \jid{admin1@example.org} and
-  \jid{admin2@example.net} can enable logging, and the embedded CSS file will be
-  used. The names of the log files will only contain the day (number),
-  and there will be subdirectories for each year and month. The log files will
-  be stored in /var/www/muclogs, and the local time will be used. Finally, the
-  top link will be the default \verb|<a href="/">Home</a>|.
-\begin{verbatim}
-acl: 
-  admin: 
-    user: 
-      - "admin1": "example.org"
-      - "admin2": "example.net"
-access: 
-  muc_log: 
-    admin: allow
-    all: deny
-
-modules: 
-  ...
-  mod_muc_log: 
-    access_log: muc_log
-    cssfile: false
-    dirtype: subdirs
-    file_permissions:
-      mode: 644
-      group: 33
-    outdir: "/var/www/muclogs"
-    timezone: local
-  ...
-\end{verbatim}
-\end{itemize}
-
-\makesubsection{modoffline}{\modoffline{}}
-\ind{modules!\modoffline{}}
-
-This module implements offline message storage (\xepref{0160}).
-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{ejabberdctl}).
-
-\begin{description}
-  \dbtype
-  \titem{access\_max\_user\_messages: AccessName}\ind{options!access\_max\_user\_messages}
-  This option defines which access rule will be enforced to limit
-  the maximum number of offline messages that a user can have (quota).
-  When a user has too many offline messages, any new messages that he receive are discarded,
-  and a resource-constraint error is returned to the sender.
-  The default value is \term{max\_user\_offline\_messages}.
-  Then you can define an access rule with a syntax similar to 
-  \term{max\_user\_sessions} (see \ref{configmaxsessions}).
-  \titem{store\_empty\_body: true|false}\ind{options!store\_empty\_body} Whether or not
-  to store messages with empty \term{<body/>} element. The default value is \term{true}.
-\end{description}
-
-This example allows power users to have as much as 5000 offline messages,
-administrators up to 2000,
-and all the other users up to 100.
-\begin{verbatim}
-acl: 
-  admin: 
-    user: 
-      - "admin1": "localhost"
-      - "admin2": "example.org"
-  poweruser: 
-    user: 
-      - "bob": "example.org"
-      - "jane": "example.org"
-
-access: 
-  max_user_offline_messages: 
-    poweruser: 5000
-    admin: 2000
-    all: 100
-
-modules: 
-  ...
-  mod_offline: 
-    access_max_user_messages: max_user_offline_messages
-  ...
-\end{verbatim}
-
-\makesubsection{modping}{\modping{}}
-\ind{modules!\modping{}}
-
-This module implements support for XMPP Ping (\xepref{0199}) and periodic keepalives.
-When this module is enabled ejabberd responds correctly to
-ping requests, as defined in the protocol.
-
-Configuration options:
-\begin{description}
-  \titem{send\_pings: true|false}\ind{options!send\_pings}
-  If this option is set to \term{true}, the server sends pings to connected clients
-  that are not active in a given interval \term{ping\_interval}.
-  This is useful to keep client connections alive or checking availability.
-  By default this option is disabled.
-  % because it is mostly not needed and consumes resources.
-  \titem{ping\_interval: Seconds}\ind{options!ping\_interval}
-  How often to send pings to connected clients, if the previous option is enabled.
-  If a client connection does not send or receive any stanza in this interval,
-  a ping request is sent to the client.
-  The default value is 60 seconds.
-  \titem{timeout\_action: none|kill}\ind{options!timeout\_action}
-  What to do when a client does not answer to a server ping request in less than 32 seconds.
-  % Those 32 seconds are defined in ejabberd_local.erl: -define(IQ_TIMEOUT, 32000).
-  The default is to do nothing.
-\end{description}
-
-This example enables Ping responses, configures the module to send pings
-to client connections that are inactive for 4 minutes,
-and if a client does not answer to the ping in less than 32 seconds, its connection is closed:
-\begin{verbatim}
-modules:
-  ...
-  mod_ping:
-    send_pings: true
-    ping_interval: 240
-    timeout_action: kill
-  ...
-\end{verbatim}
-
-\makesubsection{modprescounter}{\modprescounter{}}
-\ind{modules!\modprescounter{}}
-
-This module detects flood/spam in presence subscription stanza traffic.
-If a user sends or receives more of those stanzas in a time interval,
-the exceeding stanzas are silently dropped, and warning is logged.
-
-Configuration options:
-\begin{description}
-  \titem{count: StanzaNumber}\ind{options!count}
-  The number of subscription presence stanzas
-  (subscribe, unsubscribe, subscribed, unsubscribed)
-  allowed for any direction (input or output)
-  per time interval.
-  Please note that two users subscribing to each other usually generate
-  4 stanzas, so the recommended value is 4 or more.
-  The default value is: 5.
-  \titem{interval: Seconds}\ind{options!interval}
-  The time interval defined in seconds.
-  The default value is 60.
-\end{description}
-
-This example enables the module, and allows up to 5 presence subscription stanzas
-to be sent or received by the users in 60 seconds:
-\begin{verbatim}
-modules:
-  ...
-  mod_pres_counter:
-    count: 5
-    interval: 60
-  ...
-\end{verbatim}
-
-\makesubsection{modprivacy}{\modprivacy{}}
-\ind{modules!\modprivacy{}}\ind{Blocking Communication}\ind{Privacy Rules}\ind{protocols!XEP-0016: Privacy Lists}
-
-This module implements \footahref{http://www.xmpp.org/extensions/xep-0016.html}{XEP-0016: Privacy Lists}.
-If end users have support for it in their \XMPP{} 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}
-\end{quote}
-
-Options:
-\begin{description}
-\iqdiscitem{Blocking Communication (\ns{jabber:iq:privacy})}
-\dbtype
-\end{description}
-
-\makesubsection{modprivate}{\modprivate{}}
-\ind{modules!\modprivate{}}\ind{protocols!XEP-0049: Private XML Storage}\ind{protocols!XEP-0048: Bookmark Storage}
-
-This module adds support for Private XML Storage (\xepref{0049}):
-\begin{quote}
-Using this method, XMPP 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 (\xepref{0048}).
-\end{quote}
-
-Options:
-\begin{description}
-\iqdiscitem{Private XML Storage (\ns{jabber:iq:private})}
-\dbtype
-\end{description}
-
-\makesubsection{modproxy}{\modproxy{}}
-\ind{modules!\modversion{}}\ind{protocols!XEP-0065: SOCKS5 Bytestreams}
-
-This module implements SOCKS5 Bytestreams (\xepref{0065}).
-It allows \ejabberd{} to act as a file transfer proxy between two
-XMPP clients.
-
-Options:
-\begin{description}
-\hostitem{proxy}
-\titem{name: Text}\ind{options!name}Defines Service Discovery name of the service.
-Default is \term{"SOCKS5 Bytestreams"}.
-\titem{ip: IP}\ind{options!ip}This option specifies which network interface
-to listen for. Default is an IP address of the service's DNS name, or,
-if fails, \verb|"127.0.0.1"|.
-\titem{port: Number}\ind{options!port}This option defines port to listen for
-incoming connections. Default is~7777.
-\titem{hostname: HostName}\ind{options!hostname}Defines a hostname advertised
-by the service when establishing a session with clients. This is useful when
-you run the service behind a NAT. The default is the value of \term{ip} option.
-Examples: \term{"proxy.mydomain.org"}, \term{"200.150.100.50"}. Note that 
-not all clients understand domain names in stream negotiation,
-so you should think twice before setting domain name in this option.
-\titem{auth\_type: anonymous|plain}\ind{options!auth\_type}SOCKS5 authentication type.
-Possible values are \term{anonymous} and \term{plain}. Default is
-\term{anonymous}.
-\titem{access: AccessName}\ind{options!access}Defines ACL for file transfer initiators.
-Default is \term{all}.
-\titem{max\_connections: Number}\ind{options!max\_connections}Maximum number of
-active connections per file transfer initiator. No limit by default.
-\titem{shaper: none|ShaperName}\ind{options!shaper}This option defines shaper for
-the file transfer peers. Shaper with the maximum bandwidth will be selected.
-Default is \term{none}.
-\end{description}
-
-Examples:
-\begin{itemize}
-\item The simpliest configuration of the module:
-\begin{verbatim}
-modules:
-  ...
-  mod_proxy65: {}
-  ...
-\end{verbatim}
-\item More complicated configuration.
-\begin{verbatim}
-acl: 
-  admin: 
-    user: 
-      - "admin": "example.org"
-  proxy_users: 
-    server: 
-      - "example.org"
-
-access: 
-  proxy65_access: 
-    proxy_users: allow
-    all: deny
-  proxy65_shaper: 
-    admin: none
-    proxy_users: proxyrate
-
-shaper: 
-  proxyrate: 10240
-
-modules: 
-  ...
-  mod_proxy65: 
-    host: "proxy1.example.org"
-    name: "File Transfer Proxy"
-    ip: "200.150.100.1"
-    port: 7778
-    max_connections: 5
-    access: proxy65_access
-    shaper: proxy65_shaper
-  ...
-\end{verbatim}
-\end{itemize}
-
-\makesubsection{modpubsub}{\modpubsub{}}
-\ind{modules!\modpubsub{}}\ind{protocols!XEP-0060: Publish-Subscribe}
-
-This module offers a Publish-Subscribe Service (\xepref{0060}).
-The functionality in \modpubsub{} can be extended using plugins.
-The plugin that implements PEP (Personal Eventing via Pubsub) (\xepref{0163})
-is enabled in the default ejabberd configuration file,
-and it requires \modcaps{}.
-
-Options:
-\begin{description}
-\hostitem{pubsub}
-  If you use \modpubsubodbc, please ensure the prefix contains only one dot,
-  for example `\jid{pubsub.}', or `\jid{publish.}',.
-\titem{access\_createnode: AccessName} \ind{options!access\_createnode}
-  This option restricts which users are allowed to create pubsub nodes using
-  ACL and ACCESS.
-  By default any account in the local ejabberd server is allowed to create pubsub nodes.
-\titem{max\_items\_node: MaxItems} \ind{options!max\_items\_node}
-  Define the maximum number of items that can be stored in a node.
-  Default value is 10.
-\titem{plugins: [ Plugin, ...]} \ind{options!plugins}
-  To specify which pubsub node plugins to use.
-  The first one in the list is used by default.
-  If this option is not defined, the default plugins list is: \term{["flat"]}.
-  PubSub clients can define which plugin to use when creating a node:
-  add \term{type='plugin-name'} attribute to the \term{create} stanza element.
-\titem{nodetree: Nodetree} \ind{options!nodetree}
-  To specify which nodetree to use.
-  If not defined, the default pubsub nodetree is used: "tree".
-  Only one nodetree can be used per host, and is shared by all node plugins.
-
-  The "virtual" nodetree does not store nodes on database.
-  This saves resources on systems with tons of nodes.
-  If using the "virtual" nodetree,
-  you can only enable those node plugins:
-  ["flat","pep"] or ["flat"];
-  any other plugins configuration will not work. 
-  Also, all nodes will have the defaut configuration,
-  and this can not be changed.
-  Using "virtual" nodetree requires to start from a clean database,
-  it will not work if you used the default "tree" nodetree before.
-
-  The "dag" nodetree provides experimental support for PubSub Collection Nodes (\xepref{0248}).
-  In that case you should also add "dag" node plugin as default, for example:
-  \term{plugins: ["dag","flat","hometree","pep"]}
-\titem{ignore\_pep\_from\_offline: false|true} \ind{options!ignore\_pep\_from\_offline}
-  To specify whether or not we should get last published PEP items
-  from users in our roster which are offline when we connect. Value is true or false.
-  If not defined, pubsub assumes true so we only get last items of online contacts.
-\titem{last\_item\_cache: false|true} \ind{options!last\_item\_cache}
-  To specify whether or not pubsub should cache last items. Value is true
-  or false. If not defined, pubsub do not cache last items. On systems with not so many nodes,
-  caching last items speeds up pubsub and allows to raise user connection rate. The cost is memory
-  usage, as every item is stored in memory.
-\titem{pep\_mapping: \{Key, Value\}} \ind{pep\_mapping}
-  This allow to define a Key-Value list to choose defined node plugins on given PEP namespace.
-  The following example will use node\_tune instead of node\_pep for every PEP node with tune namespace:
-\begin{verbatim}
-modules:
-  ...
-  mod_pubsub:
-    pep_mapping:
-      "http://jabber.org/protocol/tune": "tune"
-  ...
-\end{verbatim}
-%\titem{served\_hosts} \ind{options!served\_hosts}
-%  This option allows to create additional pubsub virtual hosts in a single module instance.
-\end{description}
-
-Example of configuration that uses flat nodes as default, and allows use of flat, nodetree and pep nodes:
-\begin{verbatim}
-modules:
-  ...
-  mod_pubsub:
-    access_createnode: pubsub_createnode
-    plugins:
-      - "flat"
-      - "hometree"
-      - "pep"
-  ...
-\end{verbatim}
-
-Using ODBC database requires using mod\_pubsub\_odbc without option changes. Only flat, hometree and pep plugins supports ODBC.
-The following example shows previous configuration with ODBC usage:
-\begin{verbatim}
-modules:
-  ...
-  mod_pubsub_odbc:
-    access_createnode: pubsub_createnode
-    plugins:
-      - "flat"
-      - "hometree"
-      - "pep"
-  ...
-\end{verbatim}
-
-\makesubsection{modregister}{\modregister{}}
-\ind{modules!\modregister{}}\ind{protocols!XEP-0077: In-Band Registration}\ind{public registration}
-
-This module adds support for In-Band Registration (\xepref{0077}). This protocol
-enables end users to use a \XMPP{} 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}
-
-
-Options:
-\begin{description}
-\titem{access: AccessName} \ind{options!access}
-  Specify rules to restrict what usernames can be registered and unregistered.
-  If a rule returns `deny' on the requested username,
-  registration and unregistration of that user name is denied.
-  There are no restrictions by default.
-\titem{access\_from: AccessName} \ind{options!access\_from}By default, \ejabberd{}
-doesn't allow to register new accounts from s2s or existing c2s sessions. You can
-change it by defining access rule in this option. Use with care: allowing registration
-from s2s leads to uncontrolled massive accounts creation by rogue users.
-\titem{captcha\_protected: false|true} \ind{options!captcha\_protected}
-Protect registrations with CAPTCHA (see section \ref{captcha}). The default is \term{false}.
-\titem{ip\_access: AccessName} \ind{options!ip\_access}
-  Define rules to allow or deny account registration depending
-  on the IP address of the XMPP client. The \term{AccessName} should be
-  of type \term{ip}. The default value is \term{all}.
-\titem{password\_strength: Entropy} \ind{options!password\_strength}
-This option sets the minimum informational entropy for passwords. The value \term{Entropy}
-is a number of bits of entropy. The recommended minimum is 32 bits.
-The default is 0, i.e. no checks are performed.
-\titem{welcome\_message: \{subject: Subject, body: Body\}}
-  \ind{options!welcomem} Set a welcome message that
-  is sent to each newly registered account. The first string is the subject, and
-  the second string is the message body.
-\titem{registration\_watchers: [ JID, ...]} \ind{options!rwatchers}This option defines a
-  list of JIDs which will be notified each time a new account is registered.
-\iqdiscitem{In-Band Registration (\ns{jabber:iq:register})}
-\end{description}
-
-This module reads also another option defined globally for the server:
-\term{registration\_timeout: Timeout}. \ind{options!registratimeout}
-This option limits the frequency of registration from a given IP or username.
-So, a user that tries to register a new account from the same IP address or JID during
-this number of seconds after his previous registration
-will receive an error \term{resource-constraint} with the explanation:
-``Users are not allowed to register accounts so quickly''.
-The timeout is expressed in seconds, and it must be an integer.
-To disable this limitation,
-instead of an integer put a word like: \term{infinity}.
-Default value: 600 seconds.
-
-Examples:
-\begin{itemize}
-\item Next example prohibits the registration of too short account names,
-and allows to create accounts only to clients of the local network:
-\begin{verbatim}
-acl: 
-  loopback:
-    ip:
-      - "127.0.0.0/8"
-      - "::1"
-  shortname: 
-    user_glob: 
-      - "?"
-      - "??"
-    ## The same using regexp:
-    ##user_regexp: "^..?$"
-
-access: 
-  mynetworks: 
-    loopback: allow
-    all: deny
-  register: 
-    shortname: deny
-    all: allow
-
-modules: 
-  mod_register: 
-    ip_access: mynetworks
-    access: register
-\end{verbatim}
-\item This configuration prohibits usage of In-Band Registration
-  to create or delete accounts,
-  but allows existing accounts to change the password:
-\begin{verbatim}
-access:
-  register:
-    all: deny
-
-modules:
-  ...
-  mod_register:
-    access: register
-  ...
-\end{verbatim}
-\item 
-  This configuration disables all In-Band Registration
-  functionality: create, delete accounts and change password:
-\begin{verbatim}
-modules:
-  ...
-  ## mod_register:
-  ##   access: register
-  ...
-\end{verbatim}
-\item Define the welcome message and two registration watchers.
-Also define a registration timeout of one hour:
-\begin{verbatim}
-registration_timeout: 3600
-modules:
-  ...
-  mod_register:
-    welcome_message:
-      subject: "Welcome!"
-      body: |-
-        Hi.
-        Welcome to this Jabber server.
-        Check http://www.jabber.org
-        
-        Bye
-    registration_watchers:
-      - "admin1@example.org"
-      - "boss@example.net"
-  ...
-\end{verbatim}
-\end{itemize}
-
-\makesubsection{modregisterweb}{\modregisterweb{}}
-\ind{modules!\modregisterweb{}}
-
-This module provides a web page where people can:
-\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 supports CAPTCHA image to register a new account.
-To enable this feature, configure the options captcha\_cmd and captcha\_host.
-
-Options:
-\begin{description}
-\titem{registration\_watchers: [ JID, ...]} \ind{options!rwatchers}This option defines a
-  list of JIDs which will be notified each time a new account is registered.
-\end{description}
-
-This example configuration shows how to enable the module and the web handler:
-\begin{verbatim}
-hosts: 
-  - "localhost"
-  - "example.org"
-  - "example.com"
-listen: 
-  ...
-  - 
-    port: 5281
-    module: ejabberd_http
-    register: true
-    certfile: "/etc/ejabberd/certificate.pem"
-    tls: true
-  ...
-
-modules: 
-  ...
-  mod_register_web: {}
-  ...
-\end{verbatim}
-
-For example, the users of the host \term{example.org} can visit the page:
-\ns{https://example.org:5281/register/}
-It is important to include the last / character in the URL,
-otherwise the subpages URL will be incorrect.
-
-\makesubsection{modroster}{\modroster{}}
-\ind{modules!\modroster{}}\ind{roster management}\ind{protocols!RFC 6121: XMPP IM}
-
-This module implements roster management as defined in
-\footahref{http://tools.ietf.org/html/rfc6121\#section-2}{RFC 6121: XMPP IM}.
-It also supports Roster Versioning (\xepref{0237}).
-
-Options:
-\begin{description}
-\iqdiscitem{Roster Management (\ns{jabber:iq:roster})}
-\dbtype
-  \titem{versioning: false|true} \ind{options!versioning}Enables
-  Roster Versioning.
-  This option is disabled by default.
-  \titem{store\_current\_id: false|true} \ind{options!storecurrentid}
-  If this option is enabled, the current version number is stored on the database.
-  If disabled, the version number is calculated on the fly each time.
-  Enabling this option reduces the load for both ejabberd and the database.
-  This option does not affect the client in any way.
-  This option is only useful if Roster Versioning is enabled.
-  This option is disabled by default.
-  Important: if you use \modsharedroster{} or \modsharedrosterldap{},
-  you must disable this option.
- \titem{access} \ind{options!access}
-   This option can be configured to specify rules to restrict roster management.
-   If a rule returns `deny' on the requested user name,
-   that user cannot modify his personal roster:
-   not add/remove/modify contacts,
-   or subscribe/unsubscribe presence.
-   By default there aren't restrictions.
- \titem{managers} \ind{options!managers}
-   List of remote entities that can manage users rosters using Remote Roster Management
-   (\xepref{0321}).
-   The protocol sections implemented are:
-   \term{4.2. The remote entity requests current user's roster}.
-   \term{4.3. The user updates roster}.
-   \term{4.4. The remote entity updates the user's roster}.
-   A remote entity cab only get or modify roster items that have the same domain as the entity.
-   Default value is: \term{[]}.
-\end{description}
-
-This example configuration enables Roster Versioning with storage of current id.
-The ICQ and MSN transports can get ICQ and MSN contacts, add them, or remove them for any local account:
-\begin{verbatim}
-modules:
-  ...
-  mod_roster:
-    versioning: true
-    store_current_id: true
-    managers:
-     - "icq.example.org"
-     - "msn.example.org"
-  ...
-\end{verbatim}
-
-With this example configuration, only admins can manage their rosters;
-everybody else cannot modify the roster:
-\begin{verbatim}
-acl:
-  admin:
-    user:
-      - "sarah": "example.org"
-access:
-  roster:
-    admin: allow
-
-modules:
-  ...
-  mod_roster:
-    access: roster
-  ...
-\end{verbatim}
-
-\makesubsection{modservicelog}{\modservicelog{}}
-\ind{modules!\modservicelog{}}\ind{message auditing}\ind{Bandersnatch}
-
-This module adds support for logging end user packets via a \XMPP{} message
-auditing service such as
-\footahref{http://www.funkypenguin.info/project/bandersnatch/}{Bandersnatch}. All user
-packets are encapsulated in a \verb|<route/>| element and sent to the specified
-service(s).
-
-Options:
-\begin{description}
-\titem{loggers: [Names, ...]} \ind{options!loggers}With this option a (list of) service(s)
-  that will receive the packets can be specified.
-\end{description}
-
-Examples:
-\begin{itemize}
-\item To log all end user packets to the Bandersnatch service running on
-  \jid{bandersnatch.example.com}:
-\begin{verbatim}
-modules:
-  ...
-  mod_service_log:
-    loggers: ["bandersnatch.example.com"]
-  ...
-\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}
-
-\makesubsection{modsharedroster}{\modsharedroster{}}
-\ind{modules!\modsharedroster{}}\ind{shared roster groups}
-
-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.
-A shared roster group can have members from any XMPP server,
-but the presence will only be available from and to members
-of the same virtual host where the group is created.
-
-Options:
-\begin{description}
-\dbtype
-\end{description}
-
-Shared roster groups can be edited \emph{only} via the Web Admin. Each group
-has a unique identification and the following parameters:
-\begin{description}
-\item[Name] The name of the group, which will be displayed in the roster.
-\item[Description] The description of the group. This parameter does not affect
-  anything.
-\item[Members] A list of JIDs of group members, entered one per line in
-  the Web Admin.
-  The special member directive \term{@all@}
-  represents all the registered users in the virtual host;
-  which is only recommended for a small server with just a few hundred users.
-  The special member directive \term{@online@}
-  represents the online users in the virtual host.
-\item[Displayed groups]
-  A list of groups that will be in the rosters of this group's members.
-  A group of other vhost can be identified with \term{groupid@vhost}
-\end{description}
-
-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|}
-    \hline Identification& Group `\texttt{club\_members}'\\
-    \hline Name& Club Members\\
-    \hline Description& Members from the computer club\\
-    \hline Members&
-    {\begin{tabular}{l}
-        \jid{member1@example.org}\\
-        \jid{member2@example.org}\\
-        \jid{member3@example.org}
-      \end{tabular}
-    }\\
-    \hline Displayed groups& \texttt{club\_members}\\
-    \hline
-  \end{tabular}
-\end{table}
-\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. Additionally, 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|}
-    \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{manager4@example.org}
-      \end{tabular}
-    }&
-    {\begin{tabular}{l}
-        \jid{marketeer1@example.org}\\
-        \jid{marketeer2@example.org}\\
-        \jid{marketeer3@example.org}\\
-        \jid{marketeer4@example.org}
-      \end{tabular}
-    }&
-    {\begin{tabular}{l}
-        \jid{saleswoman1@example.org}\\
-        \jid{salesman1@example.org}\\
-        \jid{saleswoman2@example.org}\\
-        \jid{salesman2@example.org}
-      \end{tabular}
-    }\\
-    \hline Displayed groups&
-    {\begin{tabular}{l}
-        \texttt{management}\\
-        \texttt{marketing}\\
-        \texttt{sales}
-      \end{tabular}
-    }&
-    {\begin{tabular}{l}
-        \texttt{management}\\
-        \texttt{marketing}
-      \end{tabular}
-    }&
-    {\begin{tabular}{l}
-        \texttt{management}\\
-        \texttt{sales}
-      \end{tabular}
-    }\\
-    \hline
-  \end{tabular}
-\end{table}
-\end{itemize}
-
-\makesubsection{modsharedrosterldap}{\modsharedrosterldap{}}
-\ind{modules!\modsharedrosterldap{}}\ind{shared roster groups ldap}
-
-This module lets the server administrator
-automatically populate users' rosters (contact lists) with entries based on
-users and groups defined in an LDAP-based directory.
-
-\makesubsubsection{msrlconfigparams}{Configuration parameters}
-
-The module accepts the following configuration parameters. Some of them, if
-unspecified, default to the values specified for the top level of
-configuration. This lets you avoid specifying, for example, the bind password,
-in multiple places.
-
-\makeparagraph{msrlfilters}{Filters}
-
-These parameters specify LDAP filters used to query for shared roster information.
-All of them are run against the \verb|ldap_base|.
-
-\begin{description}
-
- \titem{{\tt ldap\_rfilter}}
- So called ``Roster Filter''. Used to find names of all ``shared roster'' groups.
- See also the \verb|ldap_groupattr| parameter.
- If unspecified, defaults to the top-level parameter of the same name.
- You {\em must} specify it in some place in the configuration, there is no default.
-
- \titem{{\tt ldap\_ufilter}}
- ``User Filter'' -- used for retrieving the human-readable name of roster
- entries (usually full names of people in the roster).
- See also the parameters \verb|ldap_userdesc| and \verb|ldap_useruid|.
- If unspecified, defaults to the top-level parameter of the same name.
- If that one also is unspecified, then the filter is assembled from values of
- other parameters as follows (\verb|[ldap_SOMETHING]| is used to mean ``the
- value of the configuration parameter {\tt ldap\_SOMETHING}''):
-
-\begin{verbatim}
-(&(&([ldap_memberattr]=[ldap_memberattr_format])([ldap_groupattr]=%g))[ldap_filter])
-\end{verbatim}
-
- Subsequently {\tt \%u} and {\tt \%g} are replaced with a {\tt *}. This means
- that given the defaults, the filter sent to the LDAP server is would be
- \verb|(&(memberUid=*)(cn=*))|.  If however the {\tt ldap\_memberattr\_format}
- is something like \verb|uid=%u,ou=People,o=org|, then the filter will be
- \verb|(&(memberUid=uid=*,ou=People,o=org)(cn=*))|.
-
- \titem{{\tt ldap\_gfilter}}
- ``Group Filter'' -- used when retrieving human-readable name (a.k.a.
- ``Display Name'') and the members of a group.
- See also the parameters \verb|ldap_groupattr|, \verb|ldap_groupdesc| and \verb|ldap_memberattr|.
- If unspecified, defaults to the top-level parameter of the same name.
- If that one also is unspecified, then the filter is constructed exactly in the
- same way as {\tt User Filter}.
-
- \titem{{\tt ldap\_filter}}
- Additional filter which is AND-ed together with {\tt User Filter} and {\tt
- Group Filter}.
- If unspecified, defaults to the top-level parameter of the same name. If that
- one is also unspecified, then no additional filter is merged with the other
- filters.
-\end{description}
-
-Note that you will probably need to manually define the {\tt User} and {\tt
-Group Filter}s (since the auto-assembled ones will not work) if:
-\begin{itemize}
-\item your {\tt ldap\_memberattr\_format} is anything other than a simple {\tt \%u},
-\item {\bf and} the attribute specified with {\tt ldap\_memberattr} does not support substring matches.
-\end{itemize}
-An example where it is the case is OpenLDAP and {\tt (unique)MemberName} attribute from the {\tt groupOf(Unique)Names} objectClass.
-A symptom of this problem is that you will see messages such as the following in your {\tt slapd.log}:
-\begin{verbatim}
-get_filter: unknown filter type=130
-filter="(&(?=undefined)(?=undefined)(something=else))"
-\end{verbatim}
-
-\makesubsubsection{msrlattrs}{Attributes}
-
-These parameters specify the names of the attributes which hold interesting data
-in the entries returned by running filters specified in
-section~\ref{msrlfilters}.
-
-\begin{description}
- \titem{{\tt ldap\_groupattr}}
- The name of the attribute that holds the group name, and that is used to differentiate between them.
- Retrieved from results of the ``Roster Filter'' and ``Group Filter''.
- Defaults to {\tt cn}.
-
- \titem{{\tt ldap\_groupdesc}}
- The name of the attribute which holds the human-readable group name in the
- objects you use to represent groups.
- Retrieved from results of the ``Group Filter''.
- Defaults to whatever {\tt ldap\_groupattr} is set.
-
- \titem{{\tt ldap\_memberattr}}
- The name of the attribute which holds the IDs of the members of a group.
- Retrieved from results of the ``Group Filter''.
- Defaults to {\tt memberUid}.
-
- The name of the attribute differs depending on the {\tt objectClass} you use
- for your group objects, for example:
- \begin{description}
- \item{{\tt posixGroup}} $\rightarrow{}$ {\tt memberUid}
- \item{{\tt groupOfNames}} $\rightarrow{}$ {\tt member}
- \item{{\tt groupOfUniqueNames}} $\rightarrow{}$ {\tt uniqueMember}
- \end{description}
-
- \titem{{\tt ldap\_userdesc}}
- The name of the attribute which holds the human-readable user name.
- Retrieved from results of the ``User Filter''.
- Defaults to {\tt cn}.
-
- \titem{{\tt ldap\_useruid}}
- The name of the attribute which holds the ID of a roster item. Value of this
- attribute in the roster item objects needs to match the ID retrieved from the
- {\tt ldap\_memberattr} attribute of a group object.
- Retrieved from results of the ``User Filter''.
- Defaults to {\tt cn}.
-\end{description}
-
-\makesubsubsection{msrlcontrolparams}{Control parameters}
-
-These paramters control the behaviour of the module.
-
-\begin{description}
-
- \titem{{\tt ldap\_memberattr\_format}}
- A globbing format for extracting user ID from the value of the attribute named by
- \verb|ldap_memberattr|.
- Defaults to {\tt \%u}, which means that the whole value is the member ID. If
- you change it to something different, you may also need to specify the User
- and Group Filters manually --- see section~\ref{msrlfilters}.
-
- \titem{{\tt ldap\_memberattr\_format\_re}}
- A regex for extracting user ID from the value of the attribute named by
- \verb|ldap_memberattr|.
-
- An example value {\tt "CN=($\backslash{}\backslash{}$w*),(OU=.*,)*DC=company,DC=com"} works for user IDs such as the following:
- \begin{itemize}
- \item \texttt{CN=Romeo,OU=Montague,DC=company,DC=com}
- \item \texttt{CN=Abram,OU=Servants,OU=Montague,DC=company,DC=com}
- \item \texttt{CN=Juliet,OU=Capulet,DC=company,DC=com}
- \item \texttt{CN=Peter,OU=Servants,OU=Capulet,DC=company,DC=com}
- \end{itemize}
-
- In case:
- \begin{itemize}
- \item the option is unset,
- \item or the {\tt re} module in unavailable in the current Erlang environment,
- \item or the regular expression does not compile,
- \end{itemize}
- then instead of a regular expression, a simple format specified by {\tt
- ldap\_memberattr\_format} is used. Also, in the last two cases an error
- message is logged during the module initialization.
-
- Also, note that in all cases {\tt ldap\_memberattr\_format} (and {\em not} the
- regex version) is used for constructing the default ``User/Group Filter'' ---
- see section~\ref{msrlfilters}.
-
- \titem{{\tt ldap\_auth\_check}}
- Whether the module should check (via the ejabberd authentication subsystem)
- for existence of each user in the shared LDAP roster. See
- section~\ref{msrlconfigroster} form more information. Set to {\tt off} if you
- want to disable the check.
- Defaults to {\tt on}.
-
- \titem{{\tt ldap\_user\_cache\_validity}}
- Number of seconds for which the cache for roster item full names is considered
- fresh after retrieval. 300 by default. See section~\ref{msrlconfigroster} on
- how it is used during roster retrieval.
-
- \titem{{\tt ldap\_group\_cache\_validity}}
- Number of seconds for which the cache for group membership is considered
- fresh after retrieval. 300 by default. See section~\ref{msrlconfigroster} on
- how it is used during roster retrieval.
-\end{description}
-
-\makesubsubsection{msrlconnparams}{Connection parameters}
-
-The module also accepts the connection parameters, all of which default to the
-top-level parameter of the same name, if unspecified. See~\ref{ldapconnection}
-for more information about them.
-
-\makesubsubsection{msrlconfigroster}{Retrieving the roster}
-
-When the module is called to retrieve the shared roster for a user, the
-following algorithm is used:
-
-\begin{enumerate}
-\item \label{step:rfilter} A list of names of groups to display is created: the {\tt Roster Filter}
-is run against the base DN, retrieving the values of the attribute named by
-{\tt ldap\_groupattr}.
-
-\item Unless the group cache is fresh (see the {\tt
-ldap\_group\_cache\_validity} option), it is refreshed:
-
-  \begin{enumerate}
-  \item Information for all groups is retrieved using a single query: the {\tt
-  Group Filter} is run against the Base DN, retrieving the values of attributes
-  named by {\tt ldap\_groupattr} (group ID), {\tt ldap\_groupdesc} (group
-  ``Display Name'') and {\tt ldap\_memberattr} (IDs of group members).
-
-  \item group ``Display Name'', read from the attribute named by {\tt
-  ldap\_groupdesc}, is stored in the cache for the given group
-
-  \item the following processing takes place for each retrieved value of
-  attribute named by {\tt ldap\_memberattr}:
-    \begin{enumerate}
-    \item the user ID part of it is extracted using {\tt
-    ldap\_memberattr\_format(\_re)},
-
-    \item then (unless {\tt ldap\_auth\_check} is set to {\tt off}) for each
-    found user ID, the module checks (using the \ejabberd{} authentication
-    subsystem) whether such user exists in the given virtual host. It is
-    skipped if the check is enabled and fails.
-
-    This step is here for historical reasons. If you have a tidy DIT and
-    properly defined ``Roster Filter'' and ``Group Filter'', it is safe to
-    disable it by setting {\tt ldap\_auth\_check} to {\tt off} --- it will
-    speed up the roster retrieval.
-
-    \item the user ID is stored in the list of members in the cache for the
-    given group
-    \end{enumerate}
-  \end{enumerate}
-
-\item For each item (group name) in the list of groups retrieved in step~\ref{step:rfilter}:
-
-  \begin{enumerate}
-  \item the display name of a shared roster group is retrieved from the group
-  cache
-
-  \item for each IDs of users which belong to the group, retrieved from the
-  group cache:
-
-    \begin{enumerate}
-    \item the ID is skipped if it's the same as the one for which we are
-    retrieving the roster. This is so that the user does not have himself in
-    the roster.
-
-    \item the display name of a shared roster user is retrieved:
-      \begin{enumerate}
-      \item first, unless the user name cache is fresh (see the {\tt
-      ldap\_user\_cache\_validity} option), it is refreshed by running the
-      {\tt User Filter}, against the Base DN, retrieving the values of
-      attributes named by {\tt ldap\_useruid} and {\tt ldap\_userdesc}.
-      \item then, the display name for the given user ID is retrieved from the
-      user name cache.
-      \end{enumerate}
-    \end{enumerate}
-
-  \end{enumerate}
-
-\end{enumerate}
-
-\makesubsubsection{msrlconfigexample}{Configuration examples}
-
-Since there are many possible
-\footahref{http://en.wikipedia.org/wiki/Directory\_Information\_Tree}{DIT}
-layouts, it will probably be easiest to understand how to configure the module
-by looking at an example for a given DIT (or one resembling it).
-
-\makeparagraph{msrlconfigexampleflat}{Flat DIT}
-
-This seems to be the kind of DIT for which this module was initially designed.
-Basically there are just user objects, and group membership is stored in an
-attribute individually for each user. For example in a layout shown in
-figure~\ref{fig:msrl-dit-flat}, the group of each  user is stored in its {\tt
-ou} attribute.
-
-\begin{figure}[htbp]
-  \centering
-  \insscaleimg{0.4}{msrl-dit-flat.png}
-  \caption{Flat DIT graph}
-  \label{fig:msrl-dit-flat}
-\end{figure}
-
-Such layout has a few downsides, including:
-\begin{itemize}
-\item information duplication -- the group name is repeated in every member object
-\item difficult group management -- information about group members is not
-      centralized, but distributed between member objects
-\item inefficiency -- the list of unique group names has to be computed by iterating over all users
-\end{itemize}
-
-This however seems to be a common DIT layout, so the module keeps supporting it.
-You can use the following configuration\ldots
-\begin{verbatim}
-modules:
-  ...
-  mod_shared_roster_ldap:
-    ldap_base: "ou=flat,dc=nodomain"
-    ldap_rfilter: "(objectClass=inetOrgPerson)"
-    ldap_groupattr: "ou"
-    ldap_memberattr: "cn"
-    ldap_filter: "(objectClass=inetOrgPerson)"
-    ldap_userdesc: "displayName"
-  ...
-\end{verbatim}
-
-\ldots to be provided with a roster as shown in figure~\ref{fig:msrl-roster-flat} upon connecting as user {\tt czesio}.
-
-\begin{figure}[htbp]
-  \centering
-  \insscaleimg{1}{msrl-roster-flat.png}
-  \caption{Roster from flat DIT}
-  \label{fig:msrl-roster-flat}
-\end{figure}
-
-\makeparagraph{msrlconfigexampledeep}{Deep DIT}
-
-This type of DIT contains distinctly typed objects for users and groups -- see figure~\ref{fig:msrl-dit-deep}.
-They are shown separated into different subtrees, but it's not a requirement.
-
-\begin{figure}[htbp]
-  \centering
-  \insscaleimg{0.35}{msrl-dit-deep.png}
-  \caption{Example ``deep'' DIT graph}
-  \label{fig:msrl-dit-deep}
-\end{figure}
-
-If you use the following example module configuration with it:
-\begin{verbatim}
-modules: 
-  ...
-  mod_shared_roster_ldap: 
-    ldap_base: "ou=deep,dc=nodomain"
-    ldap_rfilter: "(objectClass=groupOfUniqueNames)"
-    ldap_filter: ""
-    ldap_gfilter: "(&(objectClass=groupOfUniqueNames)(cn=%g))"
-    ldap_groupdesc: "description"
-    ldap_memberattr: "uniqueMember"
-    ldap_memberattr_format: "cn=%u,ou=people,ou=deep,dc=nodomain"
-    ldap_ufilter: "(&(objectClass=inetOrgPerson)(cn=%u))"
-    ldap_userdesc: "displayName"
-  ...
-\end{verbatim}
-
-\ldots and connect as user {\tt czesio}, then \ejabberd{} will provide you with
-the roster shown in figure~\ref{fig:msrl-roster-deep}.
-
-\begin{figure}[htbp]
-  \centering
-  \insscaleimg{1}{msrl-roster-deep.png}
-  \caption{Example roster from ``deep'' DIT}
-  \label{fig:msrl-roster-deep}
-\end{figure}
-
-\makesubsection{modsic}{\modsic{}}
-\ind{modules!\modstats{}}\ind{protocols!XEP-0279: Server IP Check}
-
-This module adds support for Server IP Check (\xepref{0279}). This protocol
-enables a client to discover its external IP address.
-
-Options:
-\begin{description}
-\iqdiscitem{\ns{urn:xmpp:sic:0}}
-\end{description}
-
-\makesubsection{modsip}{\modsip{}}
-\ind{modules!\modsip{}}
-This module adds SIP proxy/registrar support for the corresponding virtual host.
-Note that it is not enough to just load this module only. You should also configure
-listeners and DNS records properly. See section \ref{sip} for the full explanation.
-
-Example configuration:
-\begin{verbatim}
-modules:
-  ...
-  mod_sip: {}
-  ...
-\end{verbatim}
-
-Options:
-\begin{description}
-\titem{record\_route: SIP\_URI}\ind{options!record\_route}When the option
-\term{always\_record\_route} is set or when SIP outbound
-is utilized \footahref{http://tools.ietf.org/html/rfc5626}{RFC 5626},
-\ejabberd{} inserts \term{Record-Route} header field with this \term{SIP\_URI}
-into a SIP message. The default is SIP URI constructed from the virtual host.
-\titem{always\_record\_route: true|false}\ind{options!always\_record\_route}
-Always insert \term{Record-Route} header into SIP messages. This approach allows
-to bypass NATs/firewalls a bit more easily. The default is \term{true}.
-\titem{routes: [SIP\_URI]}\ind{options!routes}You can set a list of SIP URIs of routes
-pointing to this proxy server. The default is a list of a SIP URI constructed
-from the virtual host.
-\titem{flow\_timeout\_udp: Seconds}For SIP outbound UDP connections set a keep-alive
-timer to \term{Seconds}. The default is 29.
-\titem{flow\_timeout\_tcp: Seconds}For SIP outbound TCP connections set a keep-alive
-timer to \term{Seconds}. The default is 120.
-\titem{via: [\{type: Type, host: Host, port: Port\}]}\ind{options!via}With
-this option for every \term{Type} you can specify \term{Host} and \term{Port}
-to set in \term{Via} header of outgoing SIP messages, where \term{Type} can be
-\term{udp}, \term{tcp} or \term{tls}. \term{Host} is a string and \term{Port} is 
-a non negative integer. This is useful if you're running your server in a non-standard
-network topology.
-\end{description}
-Example complex configuration:
-\begin{verbatim}
-modules:
-  ...
-  mod_sip:
-    always_record_route: false
-    record_route: sip:example.com;lr
-    routes:
-      - sip:example.com;lr
-      - sip:sip.example.com;lr
-    flow_timeout_udp: 30
-    flow_timeout_tcp: 130
-    via:
-      - 
-        type: tls
-        host: "sip-tls.example.com"
-        port: 5061
-      - 
-        type: tcp
-        host: "sip-tcp.example.com"
-        port: 5060
-      - 
-        type: udp
-        host: "sip-udp.example.com"
-        port: 5060
-  ...
-\end{verbatim}
-
-\makesubsection{modstats}{\modstats{}}
-\ind{modules!\modstats{}}\ind{protocols!XEP-0039: Statistics Gathering}\ind{statistics}
-
-This module adds support for Statistics Gathering (\xepref{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{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 XEP, 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}
-
-\makesubsection{modtime}{\modtime{}}
-\ind{modules!\modtime{}}\ind{protocols!XEP-0202: Entity Time}
-
-This module features support for Entity Time (\xepref{0202}). By using this XEP,
-you are able to discover the time at another entity's location.
-
-Options:
-\begin{description}
-\iqdiscitem{Entity Time (\ns{jabber:iq:time})}
-\end{description}
-
-\makesubsection{modvcard}{\modvcard{}}
-\ind{modules!\modvcard{}}\ind{JUD}\ind{Jabber User Directory}\ind{vCard}\ind{protocols!XEP-0054: vcard-temp}
-
-This module allows end users to store and retrieve their vCard, and to retrieve
-other users vCards, as defined in vcard-temp (\xepref{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}}
-\dbtype
-\titem{search: true|false}\ind{options!search}This option specifies whether the search
-  functionality is enabled or not
-  If disabled, the option \term{host} 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: infinity|Number}\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: false|true}\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, true|false}\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}.
-  This option is available in \modvcard when using Mnesia, but not when using ODBC storage.
-\end{description}
-
-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
-  ...
-\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}
-
-\makesubsection{modvcardldap}{\modvcardldap{}}
-\ind{modules!\modvcardldap{}}\ind{JUD}\ind{Jabber User Directory}\ind{vCard}\ind{protocols!XEP-0054: vcard-temp}
-
-%TODO: verify if the referrers to the LDAP section are still correct
-
-\ejabberd{} can map LDAP attributes to vCard fields. This behaviour is
-implemented in the \modvcardldap{} module. This module does not depend on the
-authentication method (see~\ref{ldapauth}).
-
-Usually \ejabberd{} treats LDAP as a read-only storage:
-it is possible to consult data, but not possible to
-create accounts or edit vCard that is stored in LDAP.
-However, it is possible to change passwords if \module{mod\_register} module is enabled
-and LDAP server supports
-\footahref{http://tools.ietf.org/html/rfc3062}{RFC 3062}.
-
-The \modvcardldap{} module has
-its own optional parameters. The first group of parameters has the same
-meaning as the top-level LDAP parameters to set the authentication method:
-\option{ldap\_servers}, \option{ldap\_port}, \option{ldap\_rootdn},
-\option{ldap\_password}, \option{ldap\_base}, \option{ldap\_uids},
-\option{ldap\_deref\_aliases} and \option{ldap\_filter}.
-See section~\ref{ldapauth} for detailed information
-about these options. If one of these options is not set, \ejabberd{} will look
-for the top-level option with the same name.
-
-The second group of parameters
-consists of the following \modvcardldap{}-specific options:
-
-\begin{description}
-\hostitem{vjud}
-\iqdiscitem{\ns{vcard-temp}}
-\titem{search: true|false}\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{host} 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: infinity|Number}\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{ldap\_vcard\_map: \{ Name: \{Pattern, LDAPattributes\}, ...\}} \ind{options!ldap\_vcard\_map}
-  With this option you can set the table that maps LDAP attributes to vCard fields.
-  \ind{protocols!RFC 2426: vCard MIME Directory Profile}
-  \term{Name} is the type name of the vCard as defined in
-  \footahref{http://tools.ietf.org/html/rfc2426}{RFC 2426}.
-  \term{Pattern} is a string which contains pattern variables
-  \term{"\%u"}, \term{"\%d"} or \term{"\%s"}.
-  \term{LDAPattributes} is the list containing LDAP attributes.
-  The pattern variables 
-  \term{"\%s"} will be sequentially replaced 
-  with the values of LDAP attributes from \term{List\_of\_LDAP\_attributes},
-  \term{"\%u"} will be replaced with the user part of a JID, 
-  and \term{"\%d"} will be replaced with the domain part of a JID. 
-  The default is:
-\begin{verbatim}
-"NICKNAME": {"%u": []}
-"FN": {"%s": ["displayName"]}
-"LAST": {"%s": ["sn"]}
-"FIRST": {"%s": ["givenName"]}
-"MIDDLE": {"%s": ["initials"]}
-"ORGNAME": {"%s": ["o"]}
-"ORGUNIT": {"%s": ["ou"]}
-"CTRY": {"%s": ["c"]}
-"LOCALITY": {"%s": ["l"]}
-"STREET": {"%s": ["street"]}
-"REGION": {"%s": ["st"]}
-"PCODE": {"%s": ["postalCode"]}
-"TITLE": {"%s": ["title"]}
-"URL": {"%s": ["labeleduri"]}
-"DESC": {"%s": ["description"]}
-"TEL": {"%s": ["telephoneNumber"]}
-"EMAIL": {"%s": ["mail"]}
-"BDAY": {"%s": ["birthDay"]}
-"ROLE": {"%s": ["employeeType"]}
-"PHOTO": {"%s": ["jpegPhoto"]}
-\end{verbatim}
-\titem{ldap\_search\_fields: \{ Name: Attribute, ...\}}\ind{options!ldap\_search\_fields}This option
-  defines the search form and the LDAP attributes to search within.
-  \term{Name} is the name of a search form
-  field which will be automatically translated by using the translation
-  files (see \term{msgs/*.msg} for available words). \term{Attribute} is the
-  LDAP attribute or the pattern \term{"\%u"}. The default is:
-\begin{verbatim}
-"User": "%u"
-"Full Name": "displayName"
-"Given Name": "givenName"
-"Middle Name": "initials"
-"Family Name": "sn"
-"Nickname": "%u"
-"Birthday": "birthDay"
-"Country": "c"
-"City": "l"
-"Email": "mail"
-"Organization Name": "o"
-"Organization Unit": "ou"
-\end{verbatim}
-\titem{ldap\_search\_reported: \{ SearchField: VcardField, ...\}}\ind{options!ldap\_search\_reported}This option
-  defines which search fields should be reported.
-  \term{SearchField} is the name of a search form
-  field which will be automatically translated by using the translation
-  files (see \term{msgs/*.msg} for available words). \term{VcardField} is the
-  vCard field name defined in the \option{ldap\_vcard\_map} option. The default
-  is:
-\begin{verbatim}
-"Full Name": "FN"
-"Given Name": "FIRST"
-"Middle Name": "MIDDLE"
-"Family Name": "LAST"
-"Nickname": "NICKNAME"
-"Birthday": "BDAY"
-"Country": "CTRY"
-"City": "LOCALITY"
-"Email": "EMAIL"
-"Organization Name": "ORGNAME"
-"Organization Unit": "ORGUNIT"
-\end{verbatim}
-\end{description}
-
-%TODO: this examples still should be organised better
-Examples:
-\begin{itemize}
-\item
-
-Let's say \term{ldap.example.org} is the name of our LDAP server. We have
-users with their passwords in \term{"ou=Users,dc=example,dc=org"} directory.
-Also we have addressbook, which contains users emails and their additional
-infos in \term{"ou=AddressBook,dc=example,dc=org"} directory.  Corresponding
-authentication section should looks like this:
-
-\begin{verbatim}
-## authentication method
-auth_method: ldap
-## DNS name of our LDAP server
-ldap_servers:
-  - "ldap.example.org"
-## We want to authorize users from 'shadowAccount' object class only
-ldap_filter: "(objectClass=shadowAccount)"
-\end{verbatim}
-
-Now we want to use users LDAP-info as their vCards. We have four attributes
-defined in our LDAP schema: \term{"mail"} --- email address, \term{"givenName"}
---- first name, \term{"sn"} --- second name, \term{"birthDay"} --- birthday.
-Also we want users to search each other. Let's see how we can set it up:
-
-\begin{verbatim}
-modules:
-  mod_vcard_ldap:
-    ## We use the same server and port, but want to bind anonymously because
-    ## our LDAP server accepts anonymous requests to
-    ## "ou=AddressBook,dc=example,dc=org" subtree.
-    ldap_rootdn: ""
-    ldap_password: ""
-    ## define the addressbook's base
-    ldap_base: "ou=AddressBook,dc=example,dc=org"
-    ## uidattr: user's part of JID is located in the "mail" attribute
-    ## uidattr_format: common format for our emails
-    ldap_uids: {"mail": "%u@mail.example.org"}
-    ## Now we want to define vCard pattern
-    ldap_vcard_map:
-      "NICKNAME": {"%u": []} # just use user's part of JID as his nickname
-      "FIRST": {"%s": ["givenName"]}
-      "LAST": {"%s": ["sn"]}
-      "FN": {"%s, %s": ["sn", "givenName"]} # example: "Smith, John"
-      "EMAIL": {"%s": ["mail"]}
-      "BDAY": {"%s": ["birthDay"]}
-    ## Search form
-    ldap_search_fields:
-      "User": "%u"
-      "Name": "givenName"
-      "Family Name": "sn"
-      "Email": "mail"
-      "Birthday": "birthDay"
-    ## vCard fields to be reported
-    ## Note that JID is always returned with search results
-    ldap_search_reported:
-      "Full Name": "FN"
-      "Nickname": "NICKNAME"
-      "Birthday": "BDAY"
-\end{verbatim}
-
-Note that \modvcardldap{} module checks an existence of the user before
-searching his info in LDAP.
-
-\item \term{ldap\_vcard\_map} example:
-\begin{verbatim}
-ldap_vcard_map:
-  "NICKNAME": {"%u": []} # just use user's part of JID as his nickname
-  "FN": {"%s": ["displayName"]}
-  "CTRY": {"Russia": []}
-  "EMAIL": {"%u@%d": []}
-  "DESC": {"%s\n%s": ["title", "description"]}
-\end{verbatim}
-\item \term{ldap\_search\_fields} example:
-\begin{verbatim}
-ldap_search_fields:
-  "User": "uid"
-  "Full Name": "displayName"
-  "Email": "mail"
-\end{verbatim}
-\item \term{ldap\_search\_reported} example:
-\begin{verbatim}
-ldap_search_reported:
-  "Full Name": "FN"
-  "Email": "EMAIL"
-  "Birthday": "BDAY"
-  "Nickname": "NICKNAME"
-\end{verbatim}
-\end{itemize}
-
-\makesubsection{modvcardxupdate}{\modvcardxupdate{}}
-\ind{modules!\modvcardxupdate{}}\ind{protocols!XEP-0153: vCard-Based Avatars}
-
-The user's client can store an avatar in the user vCard.
-The vCard-Based Avatars protocol (\xepref{0153})
-provides a method for clients to inform the contacts what is the avatar hash value.
-However, simple or small clients may not implement that protocol.
-
-If this module is enabled, all the outgoing client presence stanzas get automatically
-the avatar hash on behalf of the client.
-So, the contacts receive the presence stanzas with the Update Data described
-in \xepref{0153} as if the client would had inserted it itself.
-If the client had already included such element in the presence stanza,
-it is replaced with the element generated by ejabberd.
-
-By enabling this module, each vCard modification produces a hash recalculation,
-and each presence sent by a client produces hash retrieval and a
-presence stanza rewrite.
-For this reason, enabling this module will introduce a computational overhead
-in servers with clients that change frequently their presence.
-
-Options:
-\begin{description}
-\dbtype
-\end{description}
-
-\makesubsection{modversion}{\modversion{}}
-\ind{modules!\modversion{}}\ind{protocols!XEP-0092: Software Version}
-
-This module implements Software Version (\xepref{0092}). Consequently, it
-answers \ejabberd{}'s version when queried.
-
-Options:
-\begin{description}
-\titem{show\_os: true|false}\ind{options!showos}Should the operating system be revealed or not.
-  The default value is \term{true}.
-\iqdiscitem{Software Version (\ns{jabber:iq:version})}
-\end{description}
-
-\makechapter{manage}{Managing an \ejabberd{} Server}
-
-
-\makesection{ejabberdctl}{\term{ejabberdctl}}
-
-With the \term{ejabberdctl} command line administration script 
-you can execute \term{ejabberdctl commands} (described in the next section, \ref{ectl-commands})
-and also many general \term{ejabberd commands} (described in section \ref{eja-commands}).
-This means you can start, stop and perform many other administrative tasks
-in a local or remote \ejabberd{} server (by providing the argument \term{--node NODENAME}).
-
-The \term{ejabberdctl} script can be configured in the file \term{ejabberdctl.cfg}.
-This file includes detailed information about each configurable option. See section \ref{erlangconfiguration}.
-
-The \term{ejabberdctl} script returns a numerical status code.
-Success is represented by \term{0},
-error is represented by \term{1},
-and other codes may be used for specific results.
-This can be used by other scripts to determine automatically
-if a command succeeded or failed,
-for example using: \term{echo \$?}
-
-If you use Bash, you can get Bash completion by copying the file \term{tools/ejabberdctl.bc}
-to the directory \term{/etc/bash\_completion.d/} (in Debian, Ubuntu, Fedora and maybe others).
-
-\makesubsection{ectl-commands}{ejabberdctl Commands}
-
-When \term{ejabberdctl} is executed without any parameter,
-it displays the available options. If there isn't an \ejabberd{} server running,
-the available parameters are:
-\begin{description}
-\titem{start} Start \ejabberd{} in background mode. This is the default method.
-\titem{debug} Attach an Erlang shell to an already existing \ejabberd{} server. This allows to execute commands interactively in the \ejabberd{} server.
-\titem{live} Start \ejabberd{} in live mode: the shell keeps attached to the started server, showing log messages and allowing to execute interactive commands.
-\end{description}
-
-If there is an \ejabberd{} server running in the system,
-\term{ejabberdctl} shows the \term{ejabberdctl commands} described bellow
-and all the \term{ejabberd commands} available in that server (see \ref{list-eja-commands}).
-
-The \term{ejabberdctl commands} are:
-\begin{description}
-\titem{help} Get help about ejabberdctl or any available command. Try \term{ejabberdctl help help}.
-\titem{status} Check the status of the \ejabberd{} server.
-\titem{stop} Stop the \ejabberd{} server.
-\titem{restart} Restart the \ejabberd{} server.
-\titem{mnesia} Get information about the Mnesia database.
-\end{description}
-
-The \term{ejabberdctl} script can be restricted to require authentication
-and execute some \term{ejabberd commands}; see \ref{accesscommands}.
-
-If account \term{robot1@example.org} is registered in \ejabberd{} with password \term{abcdef}
-(which MD5 is E8B501798950FC58AAD83C8C14978E),
-and your old-format configuration file contains this setting:
-\begin{verbatim}
-{hosts, ["example.org"]}.
-{acl, bots, {user, "robot1", "example.org"}}.
-{access, ctlaccess, [{allow, bots}]}.
-{ejabberdctl_access_commands, [ {ctlaccess, [registered_users, register], []} ]}.
-\end{verbatim}
-then you can do this in the shell:
-\begin{verbatim}
-$ ejabberdctl registered_users example.org
-Error: no_auth_provided
-$ ejabberdctl --auth robot1 example.org abcdef registered_users example.org
-robot1
-testuser1
-testuser2
-\end{verbatim}
-
-
-\makesubsection{erlangconfiguration}{Erlang Runtime System}
-
-\ejabberd{} is an Erlang/OTP application that runs inside an Erlang runtime system.
-This system is configured using environment variables and command line parameters.
-The \term{ejabberdctl} administration script uses many of those possibilities.
-You can configure some of them with the file \term{ejabberdctl.cfg},
-which includes detailed description about them.
-This section describes for reference purposes
-all the environment variables and command line parameters.
-
-The environment variables:
-\begin{description}
-  \titem{EJABBERD\_CONFIG\_PATH}
-	Path to the ejabberd configuration file.
-  \titem{EJABBERD\_MSGS\_PATH}
-	Path to the directory with translated strings.
-  \titem{EJABBERD\_LOG\_PATH}
-	Path to the ejabberd service log file.
-  \titem{EJABBERD\_SO\_PATH}
-	Path to the directory with binary system libraries.
-  \titem{EJABBERD\_DOC\_PATH}
-	Path to the directory with ejabberd documentation.
-  \titem{EJABBERD\_PID\_PATH}
-	Path to the PID file that ejabberd can create when started.
-  \titem{HOME}
-	Path to the directory that is considered \ejabberd{}'s home.
-	This path is used to read the file \term{.erlang.cookie}.
-  \titem{ERL\_CRASH\_DUMP}
-	Path to the file where crash reports will be dumped.
-  \titem{ERL\_EPMD\_ADDRESS}
-	IP address where epmd listens for connections (see section \ref{epmd}).
-  \titem{ERL\_INETRC}
-	Indicates which IP name resolution to use.
-	If using \term{-sname}, specify either this option or \term{-kernel inetrc filepath}.
-  \titem{ERL\_MAX\_PORTS}
-	Maximum number of simultaneously open Erlang ports.
-  \titem{ERL\_MAX\_ETS\_TABLES}
-	Maximum number of ETS and Mnesia tables.
-\end{description}
-
-The command line parameters:
-\begin{description}
-  \titem{-sname ejabberd}
-	The Erlang node will be identified using only the first part
-	of the host name, i.\,e. other Erlang nodes outside this domain cannot contact
-	this node. This is the preferable option in most cases.
-  \titem{-name ejabberd}
-	The Erlang node will be fully identified.
-    This is only useful if you plan to setup an \ejabberd{} cluster with nodes in different networks.
-  \titem{-kernel inetrc '"/etc/ejabberd/inetrc"'}
-	Indicates which IP name resolution to use.
-	If using \term{-sname}, specify either this option or \term{ERL\_INETRC}.
-  \titem{-kernel inet\_dist\_listen\_min 4200 inet\_dist\_listen\_min 4210}
-	Define the first and last ports that \term{epmd} (section \ref{epmd}) can listen to.
-  \titem{-kernel inet\_dist\_use\_interface "\{ 127,0,0,1 \}"}
-	Define the IP address where this Erlang node listens for other nodes
-        connections (see section \ref{epmd}).
-  \titem{-detached}
-        Starts the Erlang system detached from the system console.
-	Useful for running daemons and background processes.
-  \titem{-noinput}
-	Ensures that the Erlang system never tries to read any input.
-	Useful for running daemons and background processes.
-  \titem{-pa /var/lib/ejabberd/ebin}
-	Specify the directory where Erlang binary files (*.beam) are located.
-  \titem{-s ejabberd}
-	Tell Erlang runtime system to start the \ejabberd{} application.
-  \titem{-mnesia dir '"/var/lib/ejabberd/"'}
-	Specify the Mnesia database directory.
-  \titem{-sasl sasl\_error\_logger \{file, "/var/log/ejabberd/erlang.log"\}}
-	Path to the Erlang/OTP system log file.
-        SASL here means ``System Architecture Support Libraries''
-        not ``Simple Authentication and Security Layer''.
-  \titem{+K [true|false]}
-	Kernel polling.
-  \titem{-smp [auto|enable|disable]}
-	SMP support.
-  \titem{+P 250000}
-	Maximum number of Erlang processes.
-  \titem{-remsh ejabberd@localhost}
-	Open an Erlang shell in a remote Erlang node.
-  \titem{-hidden}
-	The connections to other nodes are hidden (not published).
-	The result is that this node is not considered part of the cluster.
-	This is important when starting a temporary \term{ctl} or \term{debug} node.
-\end{description}
-Note that some characters need to be escaped when used in shell scripts, for instance \verb|"| and \verb|{}|.
-You can find other options in the Erlang manual page (\shell{erl -man erl}).
-
-\makesection{eja-commands}{\ejabberd{} Commands}
-
-An \term{ejabberd command} is an abstract function identified by a name,
-with a defined number and type of calling arguments and type of result
-that is registered in the \term{ejabberd\_commands} service.
-Those commands can be defined in any Erlang module and executed using any valid frontend.
-
-\ejabberd{} includes two frontends to execute \term{ejabberd commands}: the script \term{ejabberdctl} (\ref{ejabberdctl})
-and the \term{ejabberd\_xmlrpc} listener (\ref{listened-module}).
-Other known frontends that can be installed to execute ejabberd commands in different ways are:
-\term{mod\_rest} (HTTP POST service),
-\term{mod\_shcommands} (ejabberd WebAdmin page).
-
-\makesubsection{list-eja-commands}{List of ejabberd Commands}
-
-\ejabberd{} includes a few ejabberd Commands by default as listed below.
-When more modules are installed, new commands may be available in the frontends.
-
-The easiest way to get a list of the available commands, and get help for them is to use
-the ejabberdctl script:
-\begin{verbatim}
-$ ejabberdctl help
-Usage: ejabberdctl [--node nodename] [--auth user host password] command [options]
-
-Available commands in this ejabberd node:
-  backup file                  Store the database to backup file
-  connected_users              List all established sessions
-  connected_users_number       Get the number of established sessions
-  ...
-\end{verbatim}
-
-The commands included in ejabberd by default are:
-\begin{description}
-\titem{stop\_kindly delay announcement} Inform users and rooms, wait, and stop the server.
-  Provide the delay in seconds, and the announcement quoted.
-\titem{registered\_vhosts} List all registered vhosts in SERVER
-\titem{reopen\_log} Reopen the log files after they were renamed.
-  If the old files were not renamed before calling this command,
-  they are automatically renamed to \term{"*-old.log"}. See section \ref{logfiles}.
-\titem {convert\_to\_yaml /etc/ejabberd/ejabberd.cfg /etc/ejabberd/ejabberd-converted.yml}
-  Convert an old ejabberd.cfg file to the YAML syntax in a new file.
-\titem {backup ejabberd.backup}
-  Store internal Mnesia database to a binary backup file.
-\titem {restore ejabberd.backup}
-  Restore immediately from a binary backup file the internal Mnesia database.
-  This will consume a lot of memory if you have a large database,
-  so better use \term{install\_fallback}.
-\titem {install\_fallback ejabberd.backup}
-  The binary backup file is installed as fallback:
-  it will be used to restore the database at the next ejabberd start.
-  This means that, after running this command, you have to restart ejabberd.
-  This command requires less memory than \term{restore}.
-\titem {dump ejabberd.dump}
-  Dump internal Mnesia database to a text file dump.
-\titem {load ejabberd.dump}
-  Restore immediately from a text file dump.
-  This is not recommended for big databases, as it will consume much time,
-  memory and processor. In that case it's preferable to use \term{backup} and \term{install\_fallback}.
-\titem{import\_piefxis, export\_piefxis, export\_piefxis\_host} \ind{migrate between servers}
-  These options can be used to migrate accounts
-  using \xepref{0227} formatted XML files
-  from/to other Jabber/XMPP servers
-  or move users of a vhost to another ejabberd installation.
-  See also \footahref{https://support.process-one.net/doc/display/MESSENGER/ejabberd+migration+kit}{ejabberd migration kit}.
-\titem{import\_file, import\_dir} \ind{migration from other software}
-  These options can be used to migrate accounts
-  using jabberd1.4 formatted XML files.
-  from other Jabber/XMPP servers
-  There exist tutorials to
-  \footahref{http://www.ejabberd.im/migrate-to-ejabberd}{migrate from other software to ejabberd}.
-\titem{set\_master nodename}
-  Set master node of the clustered Mnesia tables.
-  If you provide as nodename "self", this node will be set as its own master.
-\titem{mnesia\_change\_nodename oldnodename newnodename oldbackup newbackup}
-  Change the erlang node name in a backup file
-\titem{export2odbc virtualhost directory} \ind{export mnesia data to SQL files}
-  Export virtual host information from Mnesia tables to SQL files.
-\titem{update\_list} List modified modules that can be updated
-\titem{update module} Update the given module, or use the keyword: all
-\titem{reload\_config} Reload ejabberd configuration file into memory
-\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.
-\titem{delete\_old\_messages days} Delete offline messages older than the given days.
-\titem{incoming\_s2s\_number} Number of incoming s2s connections on the node
-\titem{outgoing\_s2s\_number} Number of outgoing s2s connections on the node
-\titem{register user host password} Register an account in that domain with the given password.
-\titem{unregister user host} Unregister the given account.
-\titem{registered\_users host} List all registered users in HOST
-\titem{connected\_users} List all established sessions
-\titem{connected\_users\_number} Get the number of established sessions
-\titem{user\_resources user host} List user's connected resources
-\titem{kick\_user user host} Disconnect user's active sessions
-
-\end{description}
-
-\makesubsection{accesscommands}{Restrict Execution with AccessCommands}
-
-The frontends can be configured to restrict access to certain commands
-using the \term{AccessCommands}.
-In that case, authentication information must be provided.
-
-This option allows quite complex settings, so it does not use the YAML format,
-instead it uses the Erlang format.
-If you want to set that option,
-then you must move the frontend definition to another config file
-and include it using the \term{include\_config\_file} option
-(see section~\ref{includeconfigfile} and the example below).
-
-In each frontend the \term{AccessCommands} option is defined
-in a different place. But in all cases the option syntax is the same:
-\begin{verbatim}
-AccessCommands = [ {Access, CommandNames, Arguments}, ...]
-Access = atom()
-CommandNames = all | [CommandName]
-CommandName = atom()
-Arguments = [ {ArgumentName, ArgumentValue}, ...]
-ArgumentName = atom()
-ArgumentValue = any()
-\end{verbatim}
-
-The default value is to not define any restriction: \term{[]}.
-The authentication information is provided when executing a command,
-and is Username, Hostname and Password of a local XMPP account
-that has permission to execute the corresponding command.
-This means that the account must be registered in the local ejabberd,
-because the information will be verified.
-
-When one or several access restrictions are defined and the
-authentication information is provided,
-each restriction is verified until one matches completely:
-the account matches the Access rule,
-the command name is listed in CommandNames,
-and the provided arguments do not contradict Arguments.
-
-As an example to understand the syntax, let's suppose those options:
-\begin{verbatim}
-{hosts, ["example.org"]}.
-{acl, bots, {user, "robot1", "example.org"}}.
-{access, commaccess, [{allow, bots}]}.
-\end{verbatim}
-
-This list of access restrictions allows only \term{robot1@example.org} to execute all commands:
-\begin{verbatim}
-[{commaccess, all, []}]
-\end{verbatim}
-
-See another list of restrictions (the corresponding ACL and ACCESS are not shown):
-\begin{verbatim}
-[
- %% This bot can execute all commands:
- {bot, all, []},
- %% This bot can only execute the command 'dump'. No argument restriction:
- {bot_backups, [dump], []}
- %% This bot can execute all commands,
- %% but if a 'host' argument is provided, it must be "example.org":
- {bot_all_example, all, [{host, "example.org"}]},
- %% This bot can only execute the command 'register',
- %% and if argument 'host' is provided, it must be "example.org":
- {bot_reg_example, [register], [{host, "example.org"}]},
- %% This bot can execute the commands 'register' and 'unregister',
- %% if argument host is provided, it must be "test.org":
- {_bot_reg_test, [register, unregister], [{host, "test.org"}]}
-]
-\end{verbatim}
-
-In summary, you put the frontends configurations in a CFG file using Erlang format, for example a file called \term{additional.cfg}:
-\begin{verbatim}
-{ejabberdctl_access_commands, [ {ctlaccess, [registered_users, register], []} ]}.
-
-{listen, [
-  {4560, ejabberd_xmlrpc, [{maxsessions, 10}, {timeout, 5000},
-    {access_commands, [
-      {ctlaccess, [registered_users], [{host, "localhost"}]}
-    ]}
-  ]}
- ]}.
-
-{modules, [
-  {mod_rest, [
-    {allowed_ips, [ {127,0,0,1}, {192,168,1,12} ]},
-    {allowed_destinations, [ "nolan@localhost", "admin@example.com" ]},
-    {allowed_stanza_types, [ "message", "presence", "iq" ]},
-    {access_commands, [
-      {ctlaccess, [registered_users], [{host, "localhost"}]}
-    ]}
-   ]}
- ]}.
-\end{verbatim}
-and then add this line at the end of your main ejabberd configuration file, usually called \term{ejabberd.yml}:
-\begin{verbatim}
-include_config_file: "/etc/ejabberd/additional.cfg"
-\end{verbatim}
-
-\makesection{webadmin}{Web Admin}
-\ind{web admin}
-
-The \ejabberd{} Web Admin allows to administer most of \ejabberd{} using a web browser.
-
-This feature is enabled by default:
-a \term{ejabberd\_http} listener with the option \term{web\_admin} (see
-section~\ref{listened}) is included in the listening ports. 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 Admin}
-  \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
-
-The access rule \term{configure} determines what accounts can access the Web Admin and modify it.
-The access rule \term{webadmin\_view} is to grant only view access: those accounts can browse the Web Admin with read-only access.
-
-Example configurations:
-\begin{itemize}
-\item You can serve the Web Admin on the same port as the
-  \ind{protocols!XEP-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/example.com/| to administer only
-  the virtual host \jid{example.com}. Before you get access to the Web Admin
-  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@example.net}' to administer all virtual hosts (first
-  URL). If you log in with `\jid{admin@example.com}' on \\
-  \verb|http://example.org:5280/admin/server/example.com/| you can only
-  administer the virtual host \jid{example.com}.
-  The account `\jid{reviewer@example.com}' can browse that vhost in read-only mode.
-\begin{verbatim}
-acl: 
-  admin: 
-    user: 
-      - "admin": "example.net"
-
-host_config: 
-  "example.com": 
-    acl: 
-      admin: 
-        user: 
-          - "admin": "example.com"
-      viewers: 
-        user: 
-          - "reviewer": "example.com"
-
-access: 
-  configure: 
-    admin: allow
-  webadmin_view: 
-    viewers: allow
-
-hosts: 
-  - "example.org"
-
-listen: 
-  ...
-  - 
-    port: 5280
-    module: ejabberd_http
-    web_admin: true
-    http_poll: true
-  ...
-\end{verbatim}
-\item For security reasons, you can serve the Web Admin on a secured
-  connection, on a port differing from the HTTP Polling interface, and bind it
-  to the internal LAN IP. The Web Admin will be accessible by pointing your
-  web browser to \verb|https://192.168.1.1:5282/admin/|:
-\begin{verbatim}
-hosts: 
-  - "example.org"
-listen: 
-  ...
-  - 
-    port: 5280
-    module: ejabberd_http
-    http_poll: true
-  - 
-    ip: "192.168.1.1"
-    port: 5282
-    module: ejabberd_http
-    certfile: "/usr/local/etc/server.pem"
-    tls: true
-    web_admin: true
-  ...
-\end{verbatim}
-\end{itemize}
-
-Certain pages in the ejabberd Web Admin contain a link to a related
-section in the ejabberd Installation and Operation Guide.
-In order to view such links, a copy in HTML format of the Guide must
-be installed in the system.
-The file is searched by default in
-\term{"/share/doc/ejabberd/guide.html"}.
-The directory of the documentation can be specified in
-the environment variable \term{EJABBERD\_DOC\_PATH}.
-See section \ref{erlangconfiguration}.
-
-
-\makesection{adhoccommands}{Ad-hoc Commands}
-
-If you enable \modconfigure\ and \modadhoc,
-you can perform several administrative tasks in \ejabberd{}
-with an XMPP client.
-The client must support Ad-Hoc Commands (\xepref{0050}),
-and you must login in the XMPP server with
-an account with proper privileges.
-
-
-\makesection{changeerlangnodename}{Change Computer Hostname}
-
-\ejabberd{} uses the distributed Mnesia database.
-Being distributed, Mnesia enforces consistency of its file,
-so it stores the name of the Erlang node in it (see section \ref{nodename}).
-The name of an Erlang node includes the hostname of the computer.
-So, the name of the Erlang node changes
-if you change the name of the machine in which \ejabberd{} runs,
-or when you move \ejabberd{} to a different machine.
-
-You have two ways to use the old Mnesia database in an ejabberd with new node name:
-put the old node name in \term{ejabberdctl.cfg},
-or convert the database to the new node name.
-
-Those example steps will backup, convert and load the Mnesia database.
-You need to have either the old Mnesia spool dir or a backup of Mnesia.
-If you already have a backup file of the old database, you can go directly to step 5.
-You also need to know the old node name and the new node name.
-If you don't know them, look for them by executing \term{ejabberdctl}
-or in the ejabberd log files.
-
-Before starting, setup some variables:
-\begin{verbatim}
-OLDNODE=ejabberd@oldmachine
-NEWNODE=ejabberd@newmachine
-OLDFILE=/tmp/old.backup
-NEWFILE=/tmp/new.backup
-\end{verbatim}
-
-\begin{enumerate}
-\item Start ejabberd enforcing the old node name:
-\begin{verbatim}
-ejabberdctl --node $OLDNODE start
-\end{verbatim}
-
-\item Generate a backup file:
-\begin{verbatim}
-ejabberdctl --node $OLDNODE backup $OLDFILE
-\end{verbatim}
-
-\item Stop the old node:
-\begin{verbatim}
-ejabberdctl --node $OLDNODE stop
-\end{verbatim}
-
-\item Make sure there aren't files in the Mnesia spool dir. For example:
-\begin{verbatim}
-mkdir /var/lib/ejabberd/oldfiles
-mv /var/lib/ejabberd/*.* /var/lib/ejabberd/oldfiles/
-\end{verbatim}
-
-\item Start ejabberd. There isn't any need to specify the node name anymore:
-\begin{verbatim}
-ejabberdctl start
-\end{verbatim}
-
-\item Convert the backup to new node name:
-\begin{verbatim}
-ejabberdctl mnesia_change_nodename $OLDNODE $NEWNODE $OLDFILE $NEWFILE
-\end{verbatim}
-
-\item Install the backup file as a fallback:
-\begin{verbatim}
-ejabberdctl install_fallback $NEWFILE
-\end{verbatim}
-
-\item Stop ejabberd:
-\begin{verbatim}
-ejabberdctl stop
-\end{verbatim}
-You may see an error message in the log files, it's normal, so don't worry:
-\begin{verbatim}
-Mnesia(ejabberd@newmachine):
-** ERROR ** (ignoring core)
-** FATAL ** A fallback is installed and Mnesia must be restarted.
-  Forcing shutdown after mnesia_down from ejabberd@newmachine...
-\end{verbatim}
-
-\item Now you can finally start ejabberd:
-\begin{verbatim}
-ejabberdctl start
-\end{verbatim}
-
-\item Check that the information of the old database is available: accounts, rosters...
-After you finish, remember to delete the temporary backup files from public directories.
-\end{enumerate}
-
-
-\makechapter{secure}{Securing \ejabberd{}}
-
-\makesection{firewall}{Firewall Settings}
-\ind{firewall}\ind{ports}\ind{SASL}\ind{TLS}\ind{clustering!ports}
-
-You need to take the following TCP ports in mind when configuring your firewall:
-\begin{table}[H]
-  \centering
-  \begin{tabular}{|l|l|}
-    \hline {\bf Port} & {\bf Description} \\
-    \hline \hline 5222& Standard port for Jabber/XMPP client connections, plain or STARTTLS.\\
-    \hline 5223& Standard port for Jabber client connections using the old SSL method.\\
-    \hline 5269& Standard port for Jabber/XMPP server connections.\\
-    \hline 4369& EPMD (section \ref{epmd}) listens for Erlang node name requests.\\
-    \hline port range& Used for connections between Erlang nodes. This range is configurable (see section \ref{epmd}).\\
-    \hline
-  \end{tabular}
-\end{table}
-
-\makesection{epmd}{epmd}
-
-\footahref{http://www.erlang.org/doc/man/epmd.html}{epmd (Erlang Port Mapper Daemon)}
-is a small name server included in Erlang/OTP
-and used by Erlang programs when establishing distributed Erlang communications.
-\ejabberd{} needs \term{epmd} to use \term{ejabberdctl} and also when clustering \ejabberd{} nodes.
-This small program is automatically started by Erlang, and is never stopped.
-If \ejabberd{} is stopped, and there aren't any other Erlang programs
-running in the system, you can safely stop \term{epmd} if you want.
-
-\ejabberd{} runs inside an Erlang node.
-To communicate with \ejabberd{}, the script \term{ejabberdctl} starts a new Erlang node
-and connects to the Erlang node that holds \ejabberd{}.
-In order for this communication to work,
-\term{epmd} must be running and listening for name requests in the port 4369.
-You should block the port 4369 in the firewall in such a way that
-only the programs in your machine can access it.
-or configure the option \term{ERL\_EPMD\_ADDRESS} in the file \term{ejabberdctl.cfg}.
-
-If you build a cluster of several \ejabberd{} instances,
-each \ejabberd{} instance is called an \ejabberd{} node.
-Those \ejabberd{} nodes use a special Erlang communication method to
-build the cluster, and EPMD is again needed listening in the port 4369.
-So, if you plan to build a cluster of \ejabberd{} nodes
-you must open the port 4369 for the machines involved in the cluster.
-Remember to block the port so Internet doesn't have access to it.
-
-Once an Erlang node solved the node name of another Erlang node using EPMD and port 4369,
-the nodes communicate directly.
-The ports used in this case by default are random,
-but can be configured in the file \term{ejabberdctl.cfg}.
-The Erlang command-line parameter used internally is, for example:
-\begin{verbatim}
-erl ... -kernel inet_dist_listen_min 4370 inet_dist_listen_max 4375
-\end{verbatim}
-It is also possible to configure in \term{ejabberdctl.cfg}
-the network interface where the Erlang node will listen and accept connections.
-The Erlang command-line parameter used internally is, for example:
-\begin{verbatim}
-erl ... -kernel inet_dist_use_interface "{127,0,0,1}"
-\end{verbatim}
-
-
-\makesection{cookie}{Erlang Cookie}
-
-The Erlang cookie is a string with numbers and letters.
-An Erlang node reads the cookie at startup from the command-line parameter \term{-setcookie}.
-If not indicated, the cookie is read from the cookie file \term{\$HOME/.erlang.cookie}.
-If this file does not exist, it is created immediately with a random cookie.
-Two Erlang nodes communicate only if they have the same cookie.
-Setting a cookie on the Erlang node allows you to structure your Erlang network
-and define which nodes are allowed to connect to which.
-
-Thanks to Erlang cookies, you can prevent access to the Erlang node by mistake,
-for example when there are several Erlang nodes running different programs in the same machine.
-
-Setting a secret cookie is a simple method
-to difficult unauthorized access to your Erlang node.
-However, the cookie system is not ultimately effective
-to prevent unauthorized access or intrusion to an Erlang node.
-The communication between Erlang nodes are not encrypted,
-so the cookie could be read sniffing the traffic on the network.
-The recommended way to secure the Erlang node is to block the port 4369.
-
-
-\makesection{nodename}{Erlang Node Name}
-
-An Erlang node may have a node name.
-The name can be short (if indicated with the command-line parameter \term{-sname})
-or long (if indicated with the parameter \term{-name}).
-Starting an Erlang node with -sname limits the communication between Erlang nodes to the LAN.
-
-Using the option \term{-sname} instead of \term{-name} is a simple method
-to difficult unauthorized access to your Erlang node.
-However, it is not ultimately effective  to prevent access to the Erlang node,
-because it may be possible to fake the fact that you are on another network
-using a modified version of Erlang \term{epmd}.
-The recommended way to secure the Erlang node is to block the port 4369.
-
-
-\makesection{secure-files}{Securing Sensitive Files}
-
-\ejabberd{} stores sensitive data in the file system either in plain text or binary files.
-The file system permissions should be set to only allow the proper user to read,
-write and execute those files and directories.
-
-\begin{description}
-  \titem{ejabberd configuration file: /etc/ejabberd/ejabberd.yml}
-  Contains the JID of administrators
-  and passwords of external components.
-  The backup files probably contain also this information,
-  so it is preferable to secure the whole \term{/etc/ejabberd/} directory.
-  \titem{ejabberd service log: /var/log/ejabberd/ejabberd.log}
-  Contains IP addresses of clients.
-  If the loglevel is set to 5, it contains whole conversations and passwords.
-  If a logrotate system is used, there may be several log files with similar information,
-  so it is preferable to secure the whole \term{/var/log/ejabberd/} directory.
-  \titem{Mnesia database spool files in /var/lib/ejabberd/}
-  The files store binary data, but some parts are still readable.
-  The files are generated by Mnesia and their permissions cannot be set directly,
-  so it is preferable to secure the whole \term{/var/lib/ejabberd/} directory.
-  \titem{Erlang cookie file: /var/lib/ejabberd/.erlang.cookie}
-  See section \ref{cookie}.
-\end{description}
-
-
-\makechapter{clustering}{Clustering}
-\ind{clustering}
-
-\makesection{howitworks}{How it Works}
-\ind{clustering!how it works}
-
-A \XMPP{} 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
-connections, registered services, etc\ldots
-
-Each \ejabberd{} node has the following modules:
-\begin{itemize}
-\item router,
-\item local router,
-\item session manager,
-\item s2s manager.
-\end{itemize}
-
-\makesubsection{router}{Router}
-\ind{clustering!router}
-
-This module is the main router of \XMPP{} 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.
-
-\makesubsection{localrouter}{Local Router}
-\ind{clustering!local router}
-
-This module routes packets which have a destination domain equal to
-one of this server's host names. If the destination JID has a non-empty user
-part, it is routed to the session manager, otherwise it is processed depending
-on its content.
-
-\makesubsection{sessionmanager}{Session Manager}
-\ind{clustering!session manager}
-
-This module routes packets to local users. It looks up to which user
-resource a packet must be sent via a presence table. Then the packet is
-either routed to the appropriate c2s process, or stored in offline
-storage, or bounced back.
-
-\makesubsection{s2smanager}{s2s Manager}
-\ind{clustering!s2s manager}
-
-This module routes packets to other \XMPP{} 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.
-
-\makesection{cluster}{Clustering Setup}
-\ind{clustering!setup}
-
-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|-setcookie content_of_.erlang.cookie|'
-  option to all `\shell{erl}' commands below.
-
-\item On \term{second} run the following command as the \ejabberd{} daemon user,
-  in the working directory of \ejabberd{}:
-
-\begin{verbatim}
-erl -sname ejabberd \
-    -mnesia dir '"/var/lib/ejabberd/"' \
-    -mnesia extra_db_nodes "['ejabberd@first']" \
-    -s mnesia
-\end{verbatim}
-
-  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:
-
-  Note: the Mnesia directory may be different in your system.
-  To know where does ejabberd expect Mnesia to be installed by default,
-  call \ref{ejabberdctl} without options and it will show some help,
-  including the Mnesia database spool dir.
-
-\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 the database.
-
-  (alt) Change storage type of the \term{scheme} table to `RAM and disc
-  copy' on the second node via the Web Admin.
-
-
-\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|').
-
-  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.org/doc/apps/mnesia/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
-  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 a configuration similar as
-  on \term{first}: you probably do not need to duplicate `\verb|acl|'
-  and `\verb|access|' options because they will be taken from
-  \term{first}; and \verb|mod_irc| should be
-  enabled only on one machine in the cluster.
-\end{enumerate}
-
-You can repeat these steps for other machines supposed to serve this
-domain.
-
-\makesection{servicelb}{Service Load-Balancing}
-\ind{component load-balancing}
-
-% This section never had content, should it?
-% \makesubsection{componentlb}{Components Load-Balancing}
-
-\makesubsection{domainlb}{Domain Load-Balancing Algorithm}
-\ind{options!domain\_balancing}
-
-\ejabberd{} includes an algorithm to load balance the components that are plugged on an \ejabberd{} cluster. It means that you can plug one or several instances of the same component on each \ejabberd{} cluster and that the traffic will be automatically distributed.
-
-The default distribution algorithm try to deliver to a local instance of a component. If several local instances are available, one instance is chosen randomly. If no instance is available locally, one instance is chosen randomly among the remote component instances.
-
-If you need a different behaviour, you can change the load balancing behaviour with the option \option{domain\_balancing}. The syntax of the option is the following:
-\esyntax{domain\_balancing: BalancingCriteria}
-
-Several balancing criteria are available:
-\begin{itemize}
-\item \term{destination}: the full JID of the packet \term{to} attribute is used.
-\item \term{source}: the full JID of the packet \term{from} attribute is used.
-\item \term{bare\_destination}: the bare JID (without resource) of the packet \term{to} attribute is used.
-\item \term{bare\_source}: the bare JID (without resource) of the packet \term{from} attribute is used.
-\end{itemize}
-
-If the value corresponding to the criteria is the same, the same component instance in the cluster will be used.
-
-\makesubsection{lbbuckets}{Load-Balancing Buckets}
-\ind{options!domain\_balancing\_component\_number}
-
-When there is a risk of failure for a given component, domain balancing can cause service trouble. If one component is failing the service will not work correctly unless the sessions are rebalanced.
-
-In this case, it is best to limit the problem to the sessions handled by the failing component. This is what the \term{domain\_balancing\_component\_number} option does, making the load balancing algorithm not dynamic, but sticky on a fix number of component instances.
-
-The syntax is:
-\esyntax{domain\_balancing\_component\_number: Number}
-
-
-
-% TODO
-% See also the section about ejabberdctl!!!!
-%\section{Backup and Restore}
-%\label{backup}
-%\ind{backup}
-
-\makechapter{debugging}{Debugging}
-\ind{debugging}
-
-\makesection{logfiles}{Log Files}
-
-An \ejabberd{} node writes three log files:
-\begin{description}
-	\titem{ejabberd.log} is the ejabberd service log, with the messages reported by \ejabberd{} code
-        \titem{error.log} is the file accumulating error messages from \term{ejabberd.log}
-	\titem{crash.log} is the Erlang/OTP log, with the crash messages reported by Erlang/OTP using SASL (System Architecture Support Libraries)
-\end{description}
-
-The option \term{loglevel} modifies the verbosity of the file ejabberd.log. The syntax:
-\begin{description}
-    \titem{loglevel: Level} The standard form to set a global log level.
-\end{description}
-
-The possible \term{Level} are:
-\begin{description}
-	\titem{0} No ejabberd log at all (not recommended)
-	\titem{1} Critical
-	\titem{2} Error
-	\titem{3} Warning
-	\titem{4} Info
-	\titem{5} Debug
-\end{description}
-For example, the default configuration is:
-\begin{verbatim}
-loglevel: 4
-\end{verbatim}
-
-Option \term{log\_rate\_limit} is useful if you want to protect the logging
-mechanism from being overloaded by excessive amount of log messages.
-The syntax is:
-\begin{description}
-  \titem{log\_rate\_limit: N} Where N is a maximum number of log messages per second.
-  The default value is 100.
-\end{description}
-When the limit is reached the similar warning message is logged:
-\begin{verbatim}
-lager_error_logger_h dropped 800 messages in the last second that exceeded the limit of 100 messages/sec
-\end{verbatim}
-
-By default \ejabberd{} rotates the log files when they get grown above a certain size.
-The exact value is controlled by \term{log\_rotate\_size} option.
-The syntax is:
-\begin{description}
-  \titem{log\_rotate\_size: N} Where N is the maximum size of a log file in bytes.
-  The default value is 10485760 (10Mb).
-\end{description}
-
-\ejabberd{} can also rotates the log files at given date interval.
-The exact value is controlled by \term{log\_rotate\_date} option.
-The syntax is:
-\begin{description}
-  \titem{log\_rotate\_date: D} Where D is a string with syntax is taken from the syntax newsyslog uses in newsyslog.conf.
-  The default value is \term{""} (no rotation triggered by date).
-\end{description}
-
-However, you can rotate the log files manually.
-For doing this, set \term{log\_rotate\_size} option to 0 and \term{log\_rotate\_date}
-to empty list, then, when you need to rotate the files, rename and then reopen them.
-The ejabberdctl command \term{reopen-log} 
-(please refer to section \ref{ectl-commands})
-reopens the log files,
-and also renames the old ones if you didn't rename them.
-
-The option \term{log\_rotate\_count} defines the number of rotated files to keep
-by \term{reopen-log} command.
-Every such file has a numeric suffix. The exact format is:
-\begin{description}
-  \titem{log\_rotate\_count: N} The default value is 1,
-  which means only \term{ejabberd.log.0}, \term{error.log.0}
-  and \term{crash.log.0} will be kept.
-\end{description}
-
-\makesection{debugconsole}{Debug Console}
-
-The Debug Console is an Erlang shell attached to an already running \ejabberd{} server.
-With this Erlang shell, an experienced administrator can perform complex tasks.
-
-This shell gives complete control over the \ejabberd{} server,
-so it is important to use it with extremely care.
-There are some simple and safe examples in the article
-\footahref{http://www.ejabberd.im/interconnect-erl-nodes}{Interconnecting Erlang Nodes}
-
-To exit the shell, close the window or press the keys: control+c control+c.
-
-
-\makesection{watchdog}{Watchdog Alerts}
-\ind{debugging!watchdog}
-
-\ejabberd{} includes a watchdog mechanism that may be useful to developers
-when troubleshooting a problem related to memory usage.
-If a process in the \ejabberd{} server consumes more memory than the configured threshold,
-a message is sent to the XMPP accounts defined with the option
-\term{watchdog\_admins}
-\ind{options!watchdog\_admins} in the \ejabberd{} configuration file.
-
-The syntax is:
-\esyntax{watchdog\_admins: [JID, ...]}
-
-The memory consumed is measured in \term{words}:
-a word on 32-bit architecture is 4 bytes,
-and a word on 64-bit architecture is 8 bytes.
-The threshold by default is 1000000 words.
-This value can be configured with the option \term{watchdog\_large\_heap},
-or in a conversation with the watchdog alert bot.
-
-The syntax is:
-\esyntax{watchdog\_large\_heap: Number}
-
-Example configuration:
-\begin{verbatim}
-watchdog_admins:
-  - "admin2@localhost"
-  - "admin2@example.org"
-watchdog_large_heap: 30000000
-\end{verbatim}
-
-To remove watchdog admins, remove them in the option.
-To remove all watchdog admins, set the option with an empty list:
-\begin{verbatim}
-watchdog_admins: []
-\end{verbatim}
-
-\appendix{}
-
-\makechapter{i18ni10n}{Internationalization and Localization}
-\ind{xml:lang}\ind{internationalization}\ind{localization}\ind{i18n}\ind{l10n}
-
-The source code of \ejabberd{} supports localization.
-The translators can edit the
-\footahref{http://www.gnu.org/software/gettext/}{gettext} .po files
-using any capable program (KBabel, Lokalize, Poedit...) or a simple text editor.
-
-Then gettext
-is used to extract, update and export those .po files to the .msg format read by \ejabberd{}.
-To perform those management tasks, in the \term{src/} directory execute \term{make translations}.
-The translatable strings are extracted from source code to generate the file \term{ejabberd.pot}.
-This file is merged with each .po file to produce updated .po files.
-Finally those .po files are exported to .msg files, that have a format easily readable by \ejabberd{}.
-
-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'
-    type='get'
-    xml:lang='ru'>
-  <query xmlns='http://jabber.org/protocol/disco#items'/>
-</iq>
-\end{verbatim}
-
-\begin{figure}[htbp]
-  \centering
-  \insimg{discorus.png}
-  \caption{Service Discovery when \texttt{xml:lang='ru'}}
-  \label{fig:discorus}
-\end{figure}
-
-The Web Admin also supports the \verb|Accept-Language| HTTP header.
-
-\begin{figure}[htbp]
-  \centering
-  \insimg{webadmmainru.png}
-  \caption{Web Admin showing a virtual host when the web browser provides the
-     HTTP header `Accept-Language: ru'}
-  \label{fig:webadmmainru}
-\end{figure}
-
-
-\makechapter{releasenotes}{Release Notes}
-\ind{release notes}
-
-Release notes are available from \footahref{http://www.process-one.net/en/ejabberd/release\_notes/}{ejabberd Home Page}
-
-\makechapter{acknowledgements}{Acknowledgements}
-
-Thanks to all people who contributed to this guide:
-\begin{itemize}
-\item Alexey Shchepin (\ahrefurl{xmpp:aleksey@jabber.ru})
-\item Badlop (\ahrefurl{xmpp:badlop@jabberes.org})
-\item Evgeniy Khramtsov (\ahrefurl{xmpp:xram@jabber.ru})
-\item Florian Zumbiehl (\ahrefurl{xmpp:florz@florz.de})
-\item Ludovic Bocquet (\ahrefurl{xmpp:lbocquet@jabber.org})
-\item Marcin Owsiany (\ahrefurl{xmpp:marcin.owsiany@gmail.com})
-\item Michael Grigutsch (\ahrefurl{xmpp:migri@jabber.i-pobox.net})
-\item Mickael Remond (\ahrefurl{xmpp:mremond@process-one.net})
-\item Sander Devrieze (\ahrefurl{xmpp:s.devrieze@gmail.com})
-\item Sergei Golovan (\ahrefurl{xmpp:sgolovan@nes.ru})
-\item Vsevolod Pelipas (\ahrefurl{xmpp:vsevoload@jabber.ru})
-\end{itemize}
-
-
-\makechapter{copyright}{Copyright Information}
-
-Ejabberd Installation and Operation Guide.\\
-Copyright \copyright{} 2003 --- 2015 ProcessOne
-
-This document is free software; you can redistribute it and/or
-modify it under the terms of the GNU General Public License
-as published by the Free Software Foundation; either version 2
-of the License, or (at your option) any later version.
-
-This document is distributed in the hope that it will be useful,
-but WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
-GNU General Public License for more details.
-
-You should have received a copy of the GNU General Public License along with
-this document; if not, write to the Free Software Foundation, Inc., 51 Franklin
-Street, Fifth Floor, Boston, MA 02110-1301, USA.
-
-%TODO: a glossary describing common terms
-%\makesection{glossary}{Glossary}
-%\ind{glossary}
-
-%\begin{description}
-%\titem{c2s}
-%\titem{s2s}
-%\titem{STARTTLS}
-%\titem{XEP} (\XMPP{} Extension Protocol)
-%\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{XMPP}
-%\titem{LDAP} (Lightweight Directory Access Protocol) <Wikipedia>
-%\titem{ODBC} (Open Database Connectivity) <Wikipedia>
-%\titem{Virtual Hosting} <Wikipedia>
-
-%\end{description}
-
-
-
-% Remove the index from the HTML version to save size and bandwith.
-\begin{latexonly}
-\printindex
-\end{latexonly}
-
-\end{document}
-- 
cgit v1.2.3

