mirror of
https://github.com/processone/ejabberd.git
synced 2024-11-22 16:20:52 +01:00
6495 lines
249 KiB
TeX
6495 lines
249 KiB
TeX
\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}
|