diff options
Diffstat (limited to 'doc/guide.tex')
| -rw-r--r-- | doc/guide.tex | 6494 |
1 files changed, 0 insertions, 6494 deletions
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} |