diff options
Diffstat (limited to 'ejabberd-1.1.2/doc/guide.tex')
| -rw-r--r-- | ejabberd-1.1.2/doc/guide.tex | 3159 |
1 files changed, 0 insertions, 3159 deletions
diff --git a/ejabberd-1.1.2/doc/guide.tex b/ejabberd-1.1.2/doc/guide.tex deleted file mode 100644 index 174dc95a6..000000000 --- a/ejabberd-1.1.2/doc/guide.tex +++ /dev/null @@ -1,3159 +0,0 @@ -\documentclass[a4paper,10pt]{article} - -%% Packages -\usepackage{float} -\usepackage{graphics} -\usepackage{hevea} -\usepackage[pdftex,colorlinks,unicode,urlcolor=blue,linkcolor=blue, - pdftitle=Ejabberd\ Installation\ and\ Operation\ Guide,pdfauthor=Alexey\ - Shchepin,pdfsubject=ejabberd,pdfkeywords=ejabberd, - pdfpagelabels=false]{hyperref} -\usepackage{makeidx} -%\usepackage{showidx} % Only for verifying the index entries. -\usepackage{verbatim} -\usepackage{geometry} - -%% Index -\makeindex -% Remove the index anchors from the HTML version to save size and bandwith. -\newcommand{\ind}[1]{\begin{latexonly}\index{#1}\end{latexonly}} - -%% Images -\newcommand{\logoscale}{0.7} -\newcommand{\imgscale}{0.58} -\newcommand{\insimg}[1]{\insscaleimg{\imgscale}{#1}} -\newcommand{\insscaleimg}[2]{ - \imgsrc{#2}{} - \begin{latexonly} - \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} - -%% Modules -\newcommand{\module}[1]{\texttt{#1}} -\newcommand{\modadhoc}{\module{mod\_adhoc}} -\newcommand{\modannounce}{\module{mod\_announce}} -\newcommand{\modconfigure}{\module{mod\_configure}} -\newcommand{\moddisco}{\module{mod\_disco}} -\newcommand{\modecho}{\module{mod\_echo}} -\newcommand{\modirc}{\module{mod\_irc}} -\newcommand{\modlast}{\module{mod\_last}} -\newcommand{\modlastodbc}{\module{mod\_last\_odbc}} -\newcommand{\modmuc}{\module{mod\_muc}} -\newcommand{\modmuclog}{\module{mod\_muc\_log}} -\newcommand{\modoffline}{\module{mod\_offline}} -\newcommand{\modofflineodbc}{\module{mod\_offline\_odbc}} -\newcommand{\modprivacy}{\module{mod\_privacy}} -\newcommand{\modprivate}{\module{mod\_private}} -\newcommand{\modpubsub}{\module{mod\_pubsub}} -\newcommand{\modregister}{\module{mod\_register}} -\newcommand{\modroster}{\module{mod\_roster}} -\newcommand{\modrosterodbc}{\module{mod\_roster\_odbc}} -\newcommand{\modservicelog}{\module{mod\_service\_log}} -\newcommand{\modsharedroster}{\module{mod\_shared\_roster}} -\newcommand{\modstats}{\module{mod\_stats}} -\newcommand{\modtime}{\module{mod\_time}} -\newcommand{\modvcard}{\module{mod\_vcard}} -\newcommand{\modvcardldap}{\module{mod\_vcard\_ldap}} -\newcommand{\modvcardodbc}{\module{mod\_vcard\_odbc}} -\newcommand{\modversion}{\module{mod\_version}} - -%% Common options -\newcommand{\iqdiscitem}[1]{\titem{iqdisc} \ind{options!iqdisc}This specifies -the processing discipline for #1 IQ queries -(see section~\ref{sec:modiqdiscoption}).} -\newcommand{\hostitem}[1]{ - \titem{hosts} \ind{options!hosts} This option defines the hostnames of the - service (see section~\ref{sec:modhostsoption}). If neither \texttt{hosts} nor - the old \texttt{host} is present, the prefix `\jid{#1.}' is added to all - \ejabberd{} hostnames. -} - -%\newcommand{\quoting}[2][yozhik]{\begin{quotation}\textcolor{#1}{\textit{#2}}\end{quotation}} % Quotes enabled -%\renewcommand{command}[args][default]{def} -%\renewcommand{\headrule}{{\color{ejblue}% -%\hrule width\headwidth height\headrulewidth \vskip-\headrulewidth}} - -%% Title page -\include{version} -\title{Ejabberd \version\ Installation and Operation Guide} -\author{Alexey Shchepin \\ - \ahrefurl{mailto:alexey@sevcom.net} \\ - \ahrefurl{xmpp:aleksey@jabber.ru}} - -%% 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;} - -%% Footnotes -\begin{latexonly} -\global\parskip=9pt plus 3pt minus 1pt -\global\parindent=0pt -\gdef\ahrefurl#1{\href{#1}{\texttt{#1}}} -\gdef\footahref#1#2{#2\footnote{\href{#1}{\texttt{#1}}}} -\end{latexonly} -\newcommand{\tjepref}[2]{\footahref{http://www.jabber.org/jeps/jep-#1.html}{#2}} -\newcommand{\jepref}[1]{\tjepref{#1}{JEP-#1}} - -\begin{document} - -\label{titlepage} -\begin{titlepage} - \maketitle{} - - \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} - -\tableofcontents{} - -% Input introduction.tex -\input{introduction} - -\section{\aname{installsource}{Installation from Source}} -\label{sec:installsource} -\ind{installation} - -\subsection{\aname{installreq}{Installation Requirements}} -\label{sec:installreq} -\ind{installation!requirements} - -\subsubsection{\aname{installrequnix}{`Unix-like' operating systems}} -\label{sec:installrequnix} - -To compile \ejabberd{} on a `Unix-like' operating system, you need: -\begin{itemize} -\item GNU Make -\item GCC -\item libexpat 1.95 or higher -\item Erlang/OTP R9C-2 or higher -\item OpenSSL 0.9.6 or higher (optional) -\item Zlib 1.2.3 or higher (optional) -\item GNU Iconv 1.8 or higher (optional, not needed on systems with GNU libc) -\end{itemize} - -\subsubsection{\aname{installreqwin}{Windows}} -\label{sec:installreqwin} - -To compile \ejabberd{} on a Windows flavour, you need: -\begin{itemize} -\item MS Visual C++ 6.0 Compiler -\item \footahref{http://erlang.org/download.html}{Erlang/OTP R9C-2 or higher} -\item \footahref{http://sourceforge.net/project/showfiles.php?group\_id=10127\&package\_id=11277}{Expat 1.95.7 or higher} -\item -\footahref{http://www.gnu.org/software/libiconv/}{GNU Iconv 1.9.1} -(optional) -\item \footahref{http://www.slproweb.com/products/Win32OpenSSL.html}{Shining Light OpenSSL} -(to enable SSL connections) -\item \footahref{http://www.zlib.net/}{Zlib 1.2.3 or higher} -\end{itemize} - -\subsection{\aname{obtaining}{Obtaining \ejabberd{}}} -\label{sec:obtaining} - -\ind{download} -Released versions of \ejabberd{} can be obtained from \\ -\ahrefurl{http://www.process-one.net/en/projects/ejabberd/download.html}. - -\ind{Subversion repository} -The latest development version can be retrieved from the Subversion repository\@. -\begin{verbatim} - svn co http://svn.process-one.net/ejabberd/trunk ejabberd -\end{verbatim} - -\subsection{\aname{compile}{Compilation}} -\label{sec:compile} -\ind{installation!compilation} - -\subsubsection{\aname{compileunix}{`Unix-like' operating systems}} -\label{sec:compileunix} - -Compile \ejabberd{} on a `Unix-like' operating system by executing: - -\begin{verbatim} - ./configure - make - su - make install -\end{verbatim} - -These commands will: -\begin{itemize} -\item install \ejabberd{} into the directory \verb|/var/lib/ejabberd|, -\item install the configuration file into \verb|/etc/ejabberd|, -\item create a directory called \verb|/var/log/ejabberd| to store log files. -\end{itemize} - -Note: if you want to use an external database, you need to execute the configure -script with the option(s) \term{--enable-odbc} or \term{--enable-odbc ---enable-mssql}. See section~\ref{sec:database} for more information. - -\subsubsection{\aname{compilewin}{Windows}} -\label{sec:compilewin} - -\begin{itemize} -\item Install Erlang emulator (for example, into \verb|C:\Program Files\erl5.3|). -\item Install Expat library into \verb|C:\Program Files\Expat-1.95.7| - directory. - - Copy file \verb|C:\Program Files\Expat-1.95.7\Libs\libexpat.dll| - to your Windows system directory (for example, \verb|C:\WINNT| or - \verb|C:\WINNT\System32|) -\item Build and install the Iconv library into the directory - \verb|C:\Program Files\iconv-1.9.1|. - - Copy file \verb|C:\Program Files\iconv-1.9.1\bin\iconv.dll| to your - Windows system directory (more installation instructions can be found in the - file README.woe32 in the iconv distribution). - - Note: instead of copying libexpat.dll and iconv.dll to the Windows - directory, you can add the directories - \verb|C:\Program Files\Expat-1.95.7\Libs| and - \verb|C:\Program Files\iconv-1.9.1\bin| to the \verb|PATH| environment - variable. -\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.cfg| and run -\begin{verbatim} -werl -s ejabberd -name ejabberd -\end{verbatim} -\end{itemize} - -%TODO: how to compile database support on windows? - -\subsection{\aname{start}{Starting}} -\label{sec:start} -\ind{starting} -%TODO: update when the ejabberdctl script is made more userfriendly - -Execute the following command to start \ejabberd{}: -\begin{verbatim} - erl -pa /var/lib/ejabberd/ebin -name ejabberd -s ejabberd -\end{verbatim} -or -\begin{verbatim} - erl -pa /var/lib/ejabberd/ebin -sname ejabberd -s ejabberd -\end{verbatim} -In the latter case the Erlang node will be identified using only the first part -of the host name, i.\,e. other Erlang nodes outside this domain cannot contact -this node. - -Note that when using the above command, \ejabberd{} will search for the -configuration file in the current directory and will use the current directory -for storing its user database and for logging. - -To specify the path to the configuration file, the log files and the Mnesia -database directory, you may use the following command: -\begin{verbatim} - erl -pa /var/lib/ejabberd/ebin \ - -sname ejabberd \ - -s ejabberd \ - -ejabberd config \"/etc/ejabberd/ejabberd.cfg\" \ - log_path \"/var/log/ejabberd/ejabberd.log\" \ - -sasl sasl_error_logger \{file,\"/var/log/ejabberd/sasl.log\"\} \ - -mnesia dir \"/var/lib/ejabberd/spool\" -\end{verbatim} - -You can find other useful options in the Erlang manual page -(\shell{erl -man erl}). - -To use more than 1024 connections, you should set the environment variable -\verb|ERL_MAX_PORTS|: -\begin{verbatim} - export ERL_MAX_PORTS=32000 -\end{verbatim} -Note that with this value, \ejabberd{} will use more memory (approximately 6\,MB -more). - -To reduce memory usage, you may set the environment variable -\verb|ERL_FULLSWEEP_AFTER|: -\begin{verbatim} - export ERL_FULLSWEEP_AFTER=0 -\end{verbatim} -But in this case \ejabberd{} can start to work slower. - - -\section{\aname{basicconfig}{Basic Configuration}} -\label{sec:basicconfig} -\ind{configuration file} - -The configuration file will be loaded the first time you start \ejabberd{}. The -content from this file will be parsed and stored in a database. Subsequently the -configuration will be loaded from the database and any commands in the -configuration file are appended to the entries in the database. The -configuration file contains a sequence of Erlang terms. Lines beginning with a -\term{`\%'} sign are ignored. Each term is a tuple of which the first element is -the name of an option, and any further elements are that option's values. If the -configuration file do not contain for instance the `hosts' option, the old -host name(s) stored in the database will be used. - - -You can override the old values stored in the database by adding next lines to -the configuration file: -\begin{verbatim} - override_global. - override_local. - override_acls. -\end{verbatim} -With these lines the old global options, local options and ACLs will be removed -before new ones are added. - -\subsection{\aname{hostnames}{Host Names}} -\label{sec:hostnames} -\ind{options!hosts}\ind{host names} - -The option \option{hosts} defines a list containing one or more domains that -\ejabberd{} will serve. - -Examples: -\begin{itemize} -\item Serving one domain: - \begin{verbatim} - {hosts, ["example.org"]}. -\end{verbatim} -\item Serving one domain, and backwards compatible with older \ejabberd{} - versions: - \begin{verbatim} - {host, "example.org"}. -\end{verbatim} -\item Serving two domains: -\begin{verbatim} - {hosts, ["example.net", "example.com"]}. -\end{verbatim} -\end{itemize} - -\subsection{\aname{virtualhost}{Virtual Hosting}} -\label{sec:virtualhost} -\ind{virtual hosting}\ind{virtual hosts}\ind{virtual domains} - -Options can be defined separately for every virtual host using the -\term{host\_config} option.\ind{options!host\_config} It has the following -syntax: -\begin{verbatim} - {host_config, <hostname>, [<option>, <option>, ...]}. -\end{verbatim} - -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}]}. - -{host_config, "example.com", [{auth_method, ldap}, - {ldap_servers, ["localhost"]}, - {ldap_uidattr, "uid"}, - {ldap_rootdn, "dc=localdomain"}, - {ldap_rootdn, "dc=example,dc=com"}, - {ldap_password, ""}]}. -\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_server, "DSN=ejabberd;UID=ejabberd;PWD=ejabberd"}]}. - -{host_config, "example.com", [{auth_method, ldap}, - {ldap_servers, ["localhost", "otherhost"]}, - {ldap_uidattr, "uid"}, - {ldap_rootdn, "dc=localdomain"}, - {ldap_rootdn, "dc=example,dc=com"}, - {ldap_password, ""}]}. -\end{verbatim} -\end{itemize} - -\subsection{\aname{listened}{Listened Sockets}} -\label{sec:listened} -\ind{options!listen} - -The option \option{listen} defines for which addresses and ports \ejabberd{} -will listen and what services will be run on them. Each element of the list is a -tuple with the following elements: -\begin{itemize} -\item Port number. -\item Module that serves this port. -\item Options to this module. -\end{itemize} - -\ind{modules!ejabberd\_c2s}\ind{modules!ejabberd\_s2s\_in}\ind{modules!ejabberd\_service}\ind{modules!ejabberd\_http}\ind{protocols!JEP-0114: Jabber Component Protocol} -Currently next modules are implemented: -\begin{table}[H] - \centering - \def\arraystretch{1.4} - \begin{tabular}{|l|l|p{87mm}|} - \hline \texttt{ejabberd\_c2s}& Description& Handles c2s connections.\\ - \cline{2-3} & Options& \texttt{access}, \texttt{certfile}, \texttt{inet6}, - \texttt{ip}, \texttt{max\_stanza\_size}, \texttt{shaper}, \texttt{ssl}, - \texttt{tls}, \texttt{starttls}, \texttt{starttls\_required}, - \texttt{zlib}\\ - \hline \texttt{ejabberd\_s2s\_in}& Description& Handles incoming s2s - connections.\\ - \cline{2-3} & Options& \texttt{inet6}, \texttt{ip}, - \texttt{max\_stanza\_size}\\ - \hline \texttt{ejabberd\_service}& Description& Interacts with external - components (*).\\ - \cline{2-3} & Options& \texttt{access}, \texttt{hosts}, \texttt{inet6}, - \texttt{ip}, \texttt{shaper}\\ - \hline \texttt{ejabberd\_http}& Description& Handles incoming HTTP - connections.\\ - \cline{2-3} & Options& \texttt{certfile}, \texttt{http\_poll}, - \texttt{inet6}, \texttt{ip}, \texttt{tls}, \texttt{web\_admin}\\ - \hline - \end{tabular} -\end{table} - -(*) The mechanism for \footahref{http://ejabberd.jabber.ru/tutorials-transports}{external components} is defined in Jabber Component Protocol (\jepref{0114}). - -The following options are available: -\begin{description} - \titem{\{access, <access rule>\}} \ind{options!access}This option defines - access to the port. The default value is \term{all}. - \titem{\{certfile, Path\}} Path to a file containing the SSL certificate. - \titem{\{hosts, [Hostnames], [HostOptions]\}} \ind{options!hosts}This option - defines one or more hostnames of connected services and enables you to - specify additional options including \poption{\{password, Secret\}}. - \titem{http\_poll} \ind{options!http\_poll}\ind{protocols!JEP-0025: HTTP Polling}\ind{JWChat}\ind{web-based Jabber client} - This option enables HTTP Polling (\jepref{0025}) support. HTTP Polling - enables access via HTTP requests to \ejabberd{} from behind firewalls which - do not allow outgoing sockets on port 5222. - - If HTTP Polling is enabled, it will be available at - \verb|http://server:port/http-poll/|. Be aware that support for HTTP Polling - is also needed in the \Jabber{} client. Remark also that HTTP Polling can be - interesting to host a web-based \Jabber{} client such as - \footahref{http://jwchat.sourceforge.net/}{JWChat} (there is a tutorial to - \footahref{http://ejabberd.jabber.ru/jwchat}{install JWChat} with - instructions for \ejabberd{}). - \titem{inet6} \ind{options!inet6}\ind{IPv6}Set up the socket for IPv6. - \titem{\{ip, IPAddress\}} \ind{options!ip}This option specifies which network - interface to listen for. For example \verb|{ip, {192, 168, 1, 1}}|. - \titem{\{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 - readed data. For example \verb|{max_stanza_size, 65536}|. The default - value is \term{infinity}. - \titem{\{shaper, <access rule>\}} \ind{options!shaper}This option defines a - shaper for the port (see section~\ref{sec:shapers}). The default value - is \term{none}. - \titem{ssl} \ind{options!ssl}\ind{SSL}This option specifies that traffic on - the port will be encrypted using SSL. You should also set the - \option{certfile} option. It is recommended to use the \term{tls} option - instead. - \titem{starttls} \ind{options!starttls}\ind{STARTTLS}This option - specifies that STARTTLS encryption is available on connections to the port. - You should also set the \option{certfile} option. - \titem{starttls\_required} \ind{options!starttls\_required}This option - specifies that STARTTLS encryption is required on connections to the port. - No unencrypted connections will be allowed. You should also set the - \option{certfile} option. - \titem{tls} \ind{options!tls}\ind{TLS}This option specifies that traffic on - the port will be encrypted using SSL immediately after connecting. You - should also set the \option{certfile} option. - \titem{zlib} \ind{options!zlib}\ind{protocols!JEP-0138: Stream Compression}\ind{Zlib}This - option specifies that Zlib stream compression (as defined in \jepref{0138}) - is available on connections to the port. Client connections cannot use - stream compression and stream encryption simultaneously. Hence, if you - specify both \option{tls} (or \option{ssl}) and \option{zlib}, the latter - option will not affect connections (there will be no stream compression). - \titem{web\_admin} \ind{options!web\_admin}\ind{web interface}This option - enables the web interface for \ejabberd{} administration which is available - at \verb|http://server:port/admin/|. Login and password are the username and - password of one of the registered users who are granted access by the - `configure' access rule. -\end{description} - -In addition, the following options are available for s2s connections: -\begin{description} - \titem{\{s2s\_use\_starttls, true|false\}} - \ind{options!s2s\_use\_starttls}\ind{STARTTLS}This option defines whether to - use STARTTLS for s2s connections. - \titem{\{s2s\_certfile, Path\}} \ind{options!s2s\_certificate}Path to a - file containing a SSL certificate. - \titem{\{domain\_certfile, Domain, Path\}} \ind{options!domain\_certfile}Path - to the file containing the SSL certificate for the specified domain. -\end{description} - -For instance, the following configuration defines that: -\begin{itemize} -\item c2s connections are listened for on port 5222 and 5223 (SSL) and denied - for the user called `\term{bad}'. -\item s2s connections are listened for on port 5269 with STARTTLS for secured - traffic enabled. -\item Port 5280 is serving the web interface and the HTTP Polling service. Note - that it is also possible to serve them on different ports. The second - example in section~\ref{sec:webinterface} shows how exactly this can be done. -\item All users except for the administrators have a traffic of limit - 1,000\,Bytes/second -\item \ind{transports!AIM}The - \footahref{http://ejabberd.jabber.ru/pyaimt}{AIM transport} - \jid{aim.example.org} is connected to port 5233 with password - `\term{aimsecret}'. -\item \ind{transports!ICQ}The ICQ transport JIT (\jid{icq.example.org} and - \jid{sms.example.org}) is connected to port 5234 with password - `\term{jitsecret}'. -\item \ind{transports!MSN}The - \footahref{http://ejabberd.jabber.ru/pymsnt}{MSN transport} - \jid{msn.example.org} is connected to port 5235 with password - `\term{msnsecret}'. -\item \ind{transports!Yahoo}The - \footahref{http://ejabberd.jabber.ru/yahoo-transport-2}{Yahoo! transport} - \jid{yahoo.example.org} is connected to port 5236 with password - `\term{yahoosecret}'. -\item \ind{transports!Gadu-Gadu}The \footahref{http://ejabberd.jabber.ru/jabber-gg-transport}{Gadu-Gadu transport} \jid{gg.example.org} is - connected to port 5237 with password `\term{ggsecret}'. -\item \ind{transports!email notifier}The - \footahref{http://ejabberd.jabber.ru/jmc}{Jabber Mail Component} - \jid{jmc.example.org} is connected to port 5238 with password - `\term{jmcsecret}'. -\end{itemize} -\begin{verbatim} - {acl, blocked, {user, "bad"}}. - {access, c2s, [{deny, blocked}, - {allow, all}]}. - {shaper, normal, {maxrate, 1000}}. - {access, c2s_shaper, [{none, admin}, - {normal, all}]}. - {listen, - [{5222, ejabberd_c2s, [{access, c2s}, {shaper, c2s_shaper}]}, - {5223, ejabberd_c2s, [{access, c2s}, - ssl, {certfile, "/path/to/ssl.pem"}]}, - {5269, ejabberd_s2s_in, []}, - {5280, ejabberd_http, [http_poll, web_admin]}, - {5233, ejabberd_service, [{host, "aim.example.org", - [{password, "aimsecret"}]}]}, - {5234, ejabberd_service, [{hosts, ["icq.example.org", "sms.example.org"], - [{password, "jitsecret"}]}]}, - {5235, ejabberd_service, [{host, "msn.example.org", - [{password, "msnsecret"}]}]}, - {5236, ejabberd_service, [{host, "yahoo.example.org", - [{password, "yahoosecret"}]}]}, - {5237, ejabberd_service, [{host, "gg.example.org", - [{password, "ggsecret"}]}]}, - {5238, ejabberd_service, [{host, "jmc.example.org", - [{password, "jmcsecret"}]}]} - ] - }. - {s2s_use_starttls, true}. - {s2s_certfile, "/path/to/ssl.pem"}. -\end{verbatim} -Note, that for \ind{jabberd 1.4}jabberd 1.4- or \ind{WPJabber}WPJabber-based -services you have to make the transports log and do \ind{XDB}XDB by themselves: -\begin{verbatim} - <!-- - You have to add elogger and rlogger entries here when using ejabberd. - In this case the transport will do the logging. - --> - - <log id='logger'> - <host/> - <logtype/> - <format>%d: [%t] (%h): %s</format> - <file>/var/log/jabber/service.log</file> - </log> - - <!-- - Some Jabber server implementations do not provide - XDB services (for example, jabberd2 and ejabberd). - xdb_file.so is loaded in to handle all XDB requests. - --> - - <xdb id="xdb"> - <host/> - <load> - <!-- this is a lib of wpjabber or jabberd --> - <xdb_file>/usr/lib/jabber/xdb_file.so</xdb_file> - </load> - <xdb_file xmlns="jabber:config:xdb_file"> - <spool><jabberd:cmdline flag='s'>/var/spool/jabber</jabberd:cmdline></spool> - </xdb_file> - </xdb> -\end{verbatim} - -\subsection{\aname{auth}{Authentication}} -\label{sec:auth} -\ind{authentication}\ind{options!auth\_method} - -The option \option{auth\_method} defines the authentication method that is used -for user authentication: -\begin{verbatim} - {auth_method, [<method>]}. -\end{verbatim} - -The following authentication methods are supported by \ejabberd{}: -\begin{itemize} -\item internal (default) --- See section~\ref{sec:internalauth}. -\item external --- There are \footahref{http://ejabberd.jabber.ru/extauth}{some - example authentication scripts}. -\item ldap --- See section~\ref{sec:ldap}. -\item odbc --- See section~\ref{sec:mysql}, \ref{sec:pgsql}, - \ref{sec:mssql} and \ref{sec:odbc}. -\item anonymous --- See section~\ref{sec:saslanonymous}. -\end{itemize} - -\subsubsection{\aname{internalauth}{Internal}} -\label{sec:internalauth} -\ind{internal authentication}\ind{Mnesia} - -\ejabberd{} uses its internal Mnesia database as the default authentication method. - -\begin{itemize} -\item \term{auth\_method}: The value \term{internal} will enable the internal - authentication method. -\end{itemize} - -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]}]}. -{host_config, "example.net", [{auth_method, [ldap]}]}. -\end{verbatim} -\item To use internal authentication on all virtual hosts: - \begin{verbatim} -{auth_method, internal}. -\end{verbatim} -\end{itemize} - -\subsubsection{\aname{saslanonymous}{SASL Anonymous and Anonymous Login}} -\label{sec:saslanonymous} -\ind{sasl anonymous}\ind{anonymous login} - -%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{sec:virtualhost}). Note that there also -is a detailed tutorial regarding \footahref{http://support.process-one.net/doc/display/MESSENGER/Anonymous+users+support}{SASL -Anonymous and anonymous login configuration}. - -\begin{itemize} -\item \term{auth\_method}: The value \term{anonymous} will enable the anonymous - authentication method. -\item \term{allow\_multiple\_connections}: This value for this option can be - either \term{true} or \term{false} and 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}. -\item \term{anonymous\_protocol}: This option can take three values: - \term{sasl\_anon}, \term{login\_anon} or \term{both}. \term{sasl\_anon} means - that the SASL Anonymous method will be used. \term{login\_anon} means that the - anonymous login method will be used. \term{both} means that SASL Anonymous and - login anonymous are both enabled. -\end{itemize} - -Those options are defined for each virtual host with the \term{host\_config} -parameter (see section~\ref{sec: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_protocol, 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, [anonymous,internal]}, - {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, [anonymous,internal]}, - {anonymous_protocol, both}]}. -\end{verbatim} -\end{itemize} - -\subsection{\aname{accessrules}{Access Rules}} -\label{sec:accessrules} -\ind{options!acl}\ind{access rules}\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: -\begin{verbatim} - {acl, <aclname>, {<acltype>, ...}}. -\end{verbatim} - -\term{<acltype>} can be one of the following: -\begin{description} -\titem{all} Matches all JIDs. Example: -\begin{verbatim} -{acl, all, 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{\{user\_regexp, <regexp>\}} Matches any local user with a name that - matches \term{<regexp>} at the first virtual host. Example: -\begin{verbatim} -{acl, tests, {user, "^test[0-9]*$"}}. -\end{verbatim} -%$ -\titem{\{user\_regexp, <regexp>, <server>\}} Matches any user with a name - that matches \term{<regexp>} at server \term{<server>}. Example: -\begin{verbatim} -{acl, tests, {user, "^test", "example.org"}}. -\end{verbatim} -\titem{\{server\_regexp, <regexp>\}} Matches any JID from the server that - matches \term{<regexp>}. Example: -\begin{verbatim} -{acl, icq, {server, "^icq\\."}}. -\end{verbatim} -\titem{\{node\_regexp, <user\_regexp>, <server\_regexp>\}} Matches any user - with a name that matches \term{<user\_regexp>} at any server that matches - \term{<server\_regexp>}. Example: -\begin{verbatim} -{acl, yohzik, {node_regexp, "^yohzik$", "^example.(com|org)$"}}. -\end{verbatim} -\titem{\{user\_glob, <glob>\}} -\titem{\{user\_glob, <glob>, <server>\}} -\titem{\{server\_glob, <glob>\}} -\titem{\{node\_glob, <user\_glob>, <server\_glob>\}} This is 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 ACLs are pre-defined: -\begin{description} -\titem{all} Matches any JID. -\titem{none} Matches no JID. -\end{description} - -An entry allowing or denying access to different services looks similar to -this: -\begin{verbatim} - {access, <accessname>, [{allow, <aclname>}, - {deny, <aclname>}, - ... - ]}. -\end{verbatim} -When a JID is checked to have access to \term{<accessname>}, the server -sequentially checks if that JID mathes any of the ACLs that are named in the -second elements of the tuples in the list. If it matches, the first element of -the first matched tuple is returned, otherwise the value `\term{deny}' is -returned. - -Example: -\begin{verbatim} - {access, configure, [{allow, admin}]}. - {access, something, [{deny, badmans}, - {allow, all}]}. -\end{verbatim} - -The following access rules are pre-defined: -\begin{description} -\titem{all} Always returns the value `\term{allow}'. -\titem{none} Always returns the value `\term{deny}'. -\end{description} - -\subsection{\aname{shapers}{Shapers}} -\label{sec:shapers} -\ind{options!shaper}\ind{options!maxrate}\ind{shapers}\ind{maxrate}\ind{traffic speed} - -Shapers enable you to limit connection traffic. The syntax of -shapers is like this: -\begin{verbatim} - {shaper, <shapername>, <kind>}. -\end{verbatim} -Currently only one kind of shaper called \term{maxrate} is available. It has the -following syntax: -\begin{verbatim} - {maxrate, <rate>} -\end{verbatim} -where \term{<rate>} stands for the maximum allowed incomig rate in bytes per -second. - -Examples: -\begin{itemize} -\item To define a shaper named `\term{normal}' with traffic speed limited to -1,000\,bytes/second: -\begin{verbatim} - {shaper, normal, {maxrate, 1000}}. -\end{verbatim} -\item To define a shaper named `\term{fast}' with traffic speed limited to -50,000\,bytes/second: -\begin{verbatim} - {shaper, fast, {maxrate, 50000}}. -\end{verbatim} -\end{itemize} - -\subsection{Limiting Opened Sessions} -\label{sec:configmaxsessions} -\ind{options!max\_user\_sessions} - -This option 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{10}. - -Examples: -\begin{itemize} -\item To limit the number of sessions per user to 10 on all virtual -hosts: -\begin{verbatim} - {max_user_sessions, 10}. -\end{verbatim} -\item This option can be defined per virtual host (see -section~\ref{sec:virtualhost}). In next example the number of -sessions per user on the first host is six, while there is no limit on the -second host: -\begin{verbatim} - {host_config, "example.net", [{max_user_sessions, 6}]}. - {host_config, "example.com", [{max_user_sessions, infinity}]}. -\end{verbatim} -\end{itemize} - -\subsection{\aname{language}{Default Language}} -\label{sec:language} -\ind{options!language}\ind{language} - -The option \option{language} defines the default language of server strings that -can be seen by \Jabber{} clients. If a \Jabber{} client do not support -\option{xml:lang}, the specified language is used. The default value is -\term{en}. In order to take effect there must be a translation file -\term{<language>.msg} in \ejabberd{}'s \term{msgs} directory. - -Examples: -\begin{itemize} -\item To set Russian as default language: -\begin{verbatim} - {language, "ru"}. -\end{verbatim} -\item To set Spanish as default language: -\begin{verbatim} - {language, "es"}. -\end{verbatim} -\end{itemize} - - -\section{\aname{database}{Database Configuration}} -\label{sec:database} -\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 or an LDAP server to store persistant, -long-living data. \ejabberd{} is very flexible: you can configure different -authentication methods for different virtual hosts, you can configure different -authentication mechanisms for the same virtual host (fallback), you can set -different storage systems for modules, and so forth. - -The following databases are supported by \ejabberd{}: -\begin{itemize} -\item \footahref{http://www.microsoft.com/sql/}{Microsoft SQL Server} -\item \footahref{http://www.erlang.org/doc/doc-5.5.1/lib/mnesia-4.3.2/doc/}{Mnesia} -\item \footahref{http://mysql.com/}{MySQL} -\item \footahref{http://en.wikipedia.org/wiki/Open\_Database\_Connectivity}{Any ODBC compatible database} -\item \footahref{http://www.postgresql.org/}{PostgreSQL} -\end{itemize} - -The following LDAP servers are tested with \ejabberd{}: -\begin{itemize} -\item \footahref{http://www.microsoft.com/activedirectory/}{Active Directory} - (see section~\ref{sec:ad}) -\item \footahref{http://www.openldap.org/}{OpenLDAP} -\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} - -\subsection{\aname{mysql}{MySQL}} -\label{sec:mysql} -\ind{MySQL}\ind{MySQL!schema} - -Although this section will describe \ejabberd{}'s configuration when you want to -use the native MySQL driver, it does not describe MySQL's installation and -database creation. Check the MySQL documentation and the tutorial \footahref{http://support.process-one.net/doc/display/MESSENGER/Using+ejabberd+with+MySQL+native+driver}{Using ejabberd with MySQL native driver} for information regarding these topics. -Note that the tutorial contains information about \ejabberd{}'s configuration -which is duplicate to this section. - -Moreover, the file mysql.sql in the directory src/odbc might be interesting for -you. This file contains the ejabberd schema for MySQL. At the end of the file -you can find information to update your database schema. - -\subsubsection{\aname{compilemysql}{Driver Compilation}} -\label{sec:compilemysql} -\ind{MySQL!Driver Compilation} - -You can skip this step if you installed \ejabberd{} using a binary installer or -if the binary packages of \ejabberd{} you are using include support for MySQL. - -\begin{enumerate} -\item First, install the \footahref{http://support.process-one.net/doc/display/CONTRIBS/Yxa}{Erlang - MySQL library}. Make sure the compiled files are in your Erlang path; you can - put them for example in the same directory as your ejabberd .beam files. -\item Then, configure and install \ejabberd{} with ODBC support enabled (this is - also needed for native MySQL support!). This can be done, by using next - commands: - \begin{verbatim} -./configure --enable-odbc && make install -\end{verbatim} -\end{enumerate} - -\subsubsection{\aname{mysqlauth}{Authentication}} -\label{sec:mysqlauth} -\ind{MySQL!authentication} - -The option value name may be misleading, as the \term{auth\_method} name is used -for access to a relational database through ODBC, as well as through the native -MySQL interface. Anyway, the first configuration step is to define the odbc -\term{auth\_method}. For example: -\begin{verbatim} -{host_config, "public.example.org", [{auth_method, [odbc]}]}. -\end{verbatim} - -The actual database access is defined in the option \term{odbc\_server}. Its -value is used to define if we want to use ODBC, or one of the two native -interface available, PostgreSQL or MySQL. - -To use the native MySQL interface, you can pass a tuple of the following form as -parameter: -\begin{verbatim} -{mysql, "Server", "Database", "Username", "Password"} -\end{verbatim} - -\term{mysql} is a keyword that should be kept as is. For example: -\begin{verbatim} -{odbc_server, {mysql, "localhost", "test", "root", "password"}}. -\end{verbatim} - -\subsubsection{\aname{mysqlstorage}{Storage}} -\label{sec:mysqlstorage} -\ind{MySQL!storage} - -MySQL also can be used to store information into from several \ejabberd{} -modules. See section~\ref{sec:modoverview} to see which modules have a version -with the `\_odbc'. This suffix indicates that the module can be used with -relational databases like MySQL. To enable storage to your database, just make -sure that your database is running well (see previous sections), and replace the -suffix-less or ldap module variant with the odbc module variant. Keep in mind -that you cannot have several variants of the same module loaded! - -\subsection{\aname{mssql}{Microsoft SQL Server}} -\label{sec:mssql} -\ind{Microsoft SQL Server}\ind{Microsoft SQL Server!schema} - -Although this section will describe \ejabberd{}'s configuration when you want to -use Microsoft SQL Server, it does not describe Microsoft SQL Server's -installation and database creation. Check the MySQL documentation and the -tutorial \footahref{http://support.process-one.net/doc/display/MESSENGER/Using+ejabberd+with+MySQL+native+driver}{Using ejabberd with MySQL native driver} for information regarding these topics. -Note that the tutorial contains information about \ejabberd{}'s configuration -which is duplicate to this section. - -Moreover, the file mssql.sql in the directory src/odbc might be interesting for -you. This file contains the ejabberd schema for Microsoft SQL Server. At the end -of the file you can find information to update your database schema. - -\subsubsection{\aname{compilemssql}{Driver Compilation}} -\label{sec:compilemssql} -\ind{Microsoft SQL Server!Driver Compilation} - -You can skip this step if you installed \ejabberd{} using a binary installer or -if the binary packages of \ejabberd{} you are using include support for ODBC. - -If you want to use Microsoft SQL Server with ODBC, you need to configure, -compile and install \ejabberd{} with support for ODBC and Microsoft SQL Server -enabled. This can be done, by using next commands: -\begin{verbatim} -./configure --enable-odbc --enable-mssql && make install -\end{verbatim} - -\subsubsection{\aname{mssqlauth}{Authentication}} -\label{sec:mssqlauth} -\ind{Microsoft SQL Server!authentication} - -%TODO: not sure if this section is right!!!!!! - -The configuration of Microsoft SQL Server is the same as the configuration of -ODBC compatible serers (see section~\ref{sec:odbcauth}). - -\subsubsection{\aname{mssqlstorage}{Storage}} -\label{sec:mssqlstorage} -\ind{Microsoft SQL Server!storage} - -Microsoft SQL Server also can be used to store information into from several -\ejabberd{} modules. See section~\ref{sec:modoverview} to see which modules have -a version with the `\_odbc'. This suffix indicates that the module can be used -with relational databases like Microsoft SQL Server. To enable storage to your -database, just make sure that your database is running well (see previous -sections), and replace the suffix-less or ldap module variant with the odbc -module variant. Keep in mind that you cannot have several variants of the same -module loaded! - -\subsection{\aname{pgsql}{PostgreSQL}} -\label{sec:pgsql} -\ind{PostgreSQL}\ind{PostgreSQL!schema} - -Although this section will describe \ejabberd{}'s configuration when you want to -use the native PostgreSQL driver, it does not describe PostgreSQL's installation -and database creation. Check the PostgreSQL documentation and the tutorial \footahref{http://support.process-one.net/doc/display/MESSENGER/Using+ejabberd+with+MySQL+native+driver}{Using ejabberd with MySQL native driver} for information regarding these topics. -Note that the tutorial contains information about \ejabberd{}'s configuration -which is duplicate to this section. - -Also the file pg.sql in the directory src/odbc might be interesting for you. -This file contains the ejabberd schema for PostgreSQL. At the end of the file -you can find information to update your database schema. - -\subsubsection{\aname{compilepgsql}{Driver Compilation}} -\label{sec:compilepgsql} -\ind{PostgreSQL!Driver Compilation} - -You can skip this step if you installed \ejabberd{} using a binary installer or -if the binary packages of \ejabberd{} you are using include support for -PostgreSQL. - -\begin{enumerate} -\item First, install the Erlang PgSQL library from - \footahref{http://jungerl.sourceforge.net/}{Jungerl}. Make sure the compiled - files are in your Erlang path; you can put them for example in the same - directory as your ejabberd .beam files. -\item Then, configure, compile and install \ejabberd{} with ODBC support enabled - (this is also needed for native PostgreSQL support!). This can be done, by - using next commands: - \begin{verbatim} -./configure --enable-odbc && make install -\end{verbatim} -\end{enumerate} - -\subsubsection{\aname{pgsqlauth}{Authentication}} -\label{sec:pgsqlauth} -\ind{PostgreSQL!authentication} - -The option value name may be misleading, as the \term{auth\_method} name is used -for access to a relational database through ODBC, as well as through the native -PostgreSQL interface. Anyway, the first configuration step is to define the odbc -\term{auth\_method}. For example: -\begin{verbatim} -{host_config, "public.example.org", [{auth_method, [odbc]}]}. -\end{verbatim} - -The actual database access is defined in the option \term{odbc\_server}. Its -value is used to define if we want to use ODBC, or one of the two native -interface available, PostgreSQL or MySQL. - -To use the native PostgreSQL interface, you can pass a tuple of the following -form as parameter: -\begin{verbatim} -{pgsql, "Server", "Database", "Username", "Password"} -\end{verbatim} - -\term{pgsql} is a keyword that should be kept as is. For example: -\begin{verbatim} -{odbc_server, {pgsql, "localhost", "database", "ejabberd", "password"}}. -\end{verbatim} - -\subsubsection{\aname{pgsqlstorage}{Storage}} -\label{sec:pgsqlstorage} -\ind{PostgreSQL!storage} - -PostgreSQL also can be used to store information into from several \ejabberd{} -modules. See section~\ref{sec:modoverview} to see which modules have a version -with the `\_odbc'. This suffix indicates that the module can be used with -relational databases like PostgreSQL. To enable storage to your database, just -make sure that your database is running well (see previous sections), and -replace the suffix-less or ldap module variant with the odbc module variant. -Keep in mind that you cannot have several variants of the same module loaded! - -\subsection{\aname{odbc}{ODBC Compatible}} -\label{sec:odbc} -\ind{databases!ODBC} - -Although this section will describe \ejabberd{}'s configuration when you want to -use the ODBC driver, it does not describe the installation and database creation -of your database. Check the documentation of your database. The tutorial \footahref{http://support.process-one.net/doc/display/MESSENGER/Using+ejabberd+with+MySQL+native+driver}{Using ejabberd with MySQL native driver} also can help you. Note that the tutorial -contains information about \ejabberd{}'s configuration which is duplicate to -this section. - -\subsubsection{\aname{compileodbc}{Compilation}} -\label{sec:compileodbc} - -You can skip this step if you installed \ejabberd{} using a binary installer or -if the binary packages of \ejabberd{} you are using include support for -ODBC. - -\begin{enumerate} -\item First, install the \footahref{http://support.process-one.net/doc/display/CONTRIBS/Yxa}{Erlang - MySQL library}. Make sure the compiled files are in your Erlang path; you can - put them for example in the same directory as your ejabberd .beam files. -\item Then, configure, compile and install \ejabberd{} with ODBC support - enabled. This can be done, by using next commands: - \begin{verbatim} -./configure --enable-odbc && make install -\end{verbatim} -\end{enumerate} - -\subsubsection{\aname{odbcauth}{Authentication}} -\label{sec:odbcauth} -\ind{ODBC!authentication} - -The first configuration step is to define the odbc \term{auth\_method}. For -example: -\begin{verbatim} -{host_config, "public.example.org", [{auth_method, [odbc]}]}. -\end{verbatim} - -The actual database access is defined in the option \term{odbc\_server}. Its -value is used to defined if we want to use ODBC, or one of the two native -interface available, PostgreSQL or MySQL. - -To use a relational database through ODBC, you can pass the ODBC connection -string as \term{odbc\_server} parameter. For example: -\begin{verbatim} -{odbc_server, "DSN=database;UID=ejabberd;PWD=password"}. -\end{verbatim} - -\subsubsection{\aname{odbcstorage}{Storage}} -\label{sec:odbcstorage} -\ind{ODBC!storage} - -An ODBC compatible database also can be used to store information into from -several \ejabberd{} modules. See section~\ref{sec:modoverview} to see which -modules have a version with the `\_odbc'. This suffix indicates that the module -can be used with ODBC compatible relational databases. To enable storage to your -database, just make sure that your database is running well (see previous -sections), and replace the suffix-less or ldap module variant with the odbc -module variant. Keep in mind that you cannot have several variants of the same -module loaded! - -\subsection{\aname{ldap}{LDAP}} -\label{sec:ldap} -\ind{databases!LDAP} - -\ejabberd{} has built-in LDAP support. You can authenticate users against LDAP -server and use LDAP directory as vCard storage. Shared rosters are not supported -yet. - -\subsubsection{\aname{ldapconnection}{Connection}} -\label{sec:ldapconnection} - -Parameters: -\begin{description} -\titem{ldap\_server} \ind{options!ldap\_server}IP address or dns name of your -LDAP server. This option is required. -\titem{ldap\_port} \ind{options!ldap\_port}Port to connect to your LDAP server. - The default value is~389. -\titem{ldap\_rootdn} \ind{options!ldap\_rootdn}Bind DN. The default value - is~\term{""} which means `anonymous connection'. -\titem{ldap\_password} \ind{options!ldap\_password}Bind password. The default - value is \term{""}. -\end{description} - -Example: -\begin{verbatim} - {auth_method, ldap}. - {ldap_servers, ["ldap.example.org"]}. - {ldap_port, 389}. - {ldap_rootdn, "cn=Manager,dc=domain,dc=org"}. - {ldap_password, "secret"}. -\end{verbatim} - -Note that current LDAP implementation does not support SSL secured communication -and SASL authentication. - -\subsubsection{\aname{ldapauth}{Authentication}} -\label{sec:ldapauth} - -You can authenticate users against an LDAP directory. Available options are: - -\begin{description} -\titem{ldap\_base}\ind{options!ldap\_base}LDAP base directory which stores users - accounts. This option is required. -\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"}. -\titem{ldap\_filter}\ind{options!ldap\_filter}\ind{protocols!RFC 2254: The String Representation of LDAP Search Filters} - \footahref{http://www.faqs.org/rfcs/rfc2254.html}{RFC 2254} LDAP filter. The - default is \term{none}. 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. -\end{description} - -\subsubsection{\aname{ldapexamples}{Examples}} -\label{sec:ldapexamples} - -\paragraph{\aname{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. 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"}. - %% 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"}, - %% user's part of JID is located in the "mail" attribute - {ldap_uidattr, "mail"}, - %% common format for our emails - {ldap_uidattr_format, "%u@mail.example.org"}, - %% We have to define empty filter here, because entries in addressbook does not - %% belong to shadowAccount object class - {ldap_filter, ""}, - %% Now we want to define vCard pattern - {ldap_vcard_map, - [{"NICKNAME", "%u", []}, % just use user's part of JID as his nickname - {"GIVEN", "%s", ["givenName"]}, - {"FAMILY", "%s", ["sn"]}, - {"FN", "%s, %s", ["sn", "givenName"]}, % example: "Smith, John" - {"EMAIL", "%s", ["mail"]}, - {"BDAY", "%s", ["birthDay"]}]}, - %% Search form - {ldap_search_fields, - [{"User", "%u"}, - {"Name", "givenName"}, - {"Family Name", "sn"}, - {"Email", "mail"}, - {"Birthday", "birthDay"}]}, - %% vCard fields to be reported - %% Note that JID is always returned with search results - {ldap_search_reported, - [{"Full Name", "FN"}, - {"Nickname", "NICKNAME"}, - {"Birthday", "BDAY"}]} - ]} - ... - }. -\end{verbatim} - -Note that \modvcardldap{} module checks for the existence of the user before -searching in his information in LDAP. - - -\paragraph{\aname{ad}{Active Directory}} -\label{sec:ad} -\ind{databases!Active Directory} - -Active Directory is just an LDAP-server with predefined attributes. A sample -configuration is showed 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_uidattr, "sAMAccountName"}. - {ldap_filter, "(memberOf=*)"}. - - {mod_vcard_ldap, - [{ldap_vcard_map, - [{"NICKNAME", "%u", []}, - {"GIVEN", "%s", ["givenName"]}, - {"MIDDLE", "%s", ["initials"]}, - {"FAMILY", "%s", ["sn"]}, - {"FN", "%s", ["displayName"]}, - {"EMAIL", "%s", ["mail"]}, - {"ORGNAME", "%s", ["company"]}, - {"ORGUNIT", "%s", ["department"]}, - {"CTRY", "%s", ["c"]}, - {"LOCALITY", "%s", ["l"]}, - {"STREET", "%s", ["streetAddress"]}, - {"REGION", "%s", ["st"]}, - {"PCODE", "%s", ["postalCode"]}, - {"TITLE", "%s", ["title"]}, - {"URL", "%s", ["wWWHomePage"]}, - {"DESC", "%s", ["description"]}, - {"TEL", "%s", ["telephoneNumber"]}]}, - {ldap_search_fields, - [{"User", "%u"}, - {"Name", "givenName"}, - {"Family Name", "sn"}, - {"Email", "mail"}, - {"Company", "company"}, - {"Department", "department"}, - {"Role", "title"}, - {"Description", "description"}, - {"Phone", "telephoneNumber"}]}, - {ldap_search_reported, - [{"Full Name", "FN"}, - {"Nickname", "NICKNAME"}, - {"Email", "EMAIL"}]} - ] - }. -\end{verbatim} - - -\section{\aname{modules}{Modules Configuration}} -\label{sec:modules} -\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. - -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. Remark that, besides the last entry, - all entries end with a comma: - \begin{verbatim} - {modules, - [{mod_echo, []}, - {mod_time, []}, - {mod_version, []} - ]}. -\end{verbatim} -\end{itemize} - -\subsection{\aname{modoverview}{Overview}} -\label{sec:modoverview} -\ind{modules!overview}\ind{XMPP compliancy} - -The following table lists all modules available in the official \ejabberd{} -distribution. You can find more -\footahref{http://ejabberd.jabber.ru/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! - -You can see which database backend each module needs by looking at the suffix: -\begin{itemize} -\item `\_ldap', this means that the module needs an LDAP server as backend. -\item `\_odbc', this means that the module needs a supported database - (see~\ref{sec:database}) as backend. -\item No suffix, this means that the modules uses Erlang's built-in database - Mnesia as backend. -\end{itemize} - -If you want to -It is possible to use a relational database to store pieces of -information. You can do this by changing the module name to a name with an -\term{\_odbc} suffix in \ejabberd{} config file. You can use a relational -database for the following data: - -\begin{itemize} -\item Last connection date and time: Use \term{mod\_last\_odbc} instead of - \term{mod\_last}. -\item Offline messages: Use \term{mod\_offline\_odbc} instead of - \term{mod\_offline}. -\item Rosters: Use \term{mod\_roster\_odbc} instead of \term{mod\_roster}. -\item Users' VCARD: Use \term{mod\_vcard\_odbc} instead of \term{mod\_vcard}. -\end{itemize} - - -\begin{table}[H] - \centering - \begin{tabular}{|l|l|l|l|} - \hline Module & Feature & Dependencies & Needed for XMPP? \\ - \hline \hline \modadhoc{} & Ad-Hoc Commands (\jepref{0050}) & & No \\ - \hline \modannounce{} & Manage announcements & \modadhoc{} & No \\ - \hline \modconfigure{} & Support for online & \modadhoc{} & No \\ - & configuration of \ejabberd{} & & \\ - \hline \moddisco{} & Service Discovery (\jepref{0030}) & & No \\ - \hline \modecho{} & Echoes Jabber packets & & No \\ - \hline \modirc{} & IRC transport & & No \\ - \hline \modlast{} & Last Activity (\jepref{0012}) & & No \\ - \hline \modlastodbc{} & Last Activity (\jepref{0012}) & supported database (*) & No \\ - \hline \modmuc{} & Multi-User Chat (\jepref{0045}) & & No \\ - \hline \modmuclog{} & Multi-User Chat room logging & \modmuc{} & No \\ - \hline \modoffline{} & Offline message storage & & No \\ - \hline \modofflineodbc{} & Offline message storage & supported database (*) & No \\ - \hline \modprivacy{} & Blocking Communication & & Yes \\ - \hline \modprivate{} & Private XML Storage (\jepref{0049}) & & No \\ - \hline \modpubsub{} & Publish-Subscribe (\jepref{0060}) & & No \\ - \hline \modregister{} & In-Band Registration (\jepref{0077}) & & No \\ - \hline \modroster{} & Roster management & & Yes (**) \\ - \hline \modrosterodbc{} & Roster management & supported database (*) & Yes (**) \\ - \hline \modservicelog{} & Copy user messages to logger service & & No \\ - \hline \modsharedroster{} & Shared roster management & \modroster{} or & No \\ - & & \modrosterodbc{} & \\ - \hline \modstats{} & Statistics Gathering (\jepref{0039}) & & No \\ - \hline \modtime{} & Entity Time (\jepref{0090}) & & No \\ - \hline \modvcard{} & vcard-temp (\jepref{0054}) & & No \\ - \hline \modvcardldap{} & vcard-temp (\jepref{0054}) & LDAP server & No \\ - \hline \modvcardodbc{} & vcard-temp (\jepref{0054}) & supported database (*) & No \\ - \hline \modversion{} & Software Version (\jepref{0092}) & & No\\ - \hline - \end{tabular} -\end{table} - -\begin{itemize} -\item (*) For a list of supported databases, see section~\ref{sec:database}. -\item (**) This module or a similar one with another database backend is needed for -XMPP compliancy. -\end{itemize} - -\subsection{\aname{modcommonoptions}{Common Options}} -\label{sec:modcommonoptions} - -The following options are used by many modules. Therefore, they are described in -this separate section. - -\subsubsection{\option{\aname{modiqdiscoption}{iqdisc}}} -\label{sec:modiqdiscoption} -\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. Possible values are: -\begin{description} -\titem{no\_queue} All queries of a namespace with this processing discipline are - processed immediately. This also means that no other packets can be processed - until this one has been completely processed. Hence this discipline is not - recommended if the processing of a query can take a relatively long time. -\titem{one\_queue} In this case a separate queue is created for the processing - of IQ queries of a namespace with this discipline. In addition, the processing - of this queue is done in parallel with that of other packets. This discipline - is most recommended. -\titem{parallel} For every packet with this discipline a separate Erlang process - is spawned. Consequently, all these packets are processed in parallel. - Although spawning of Erlang process has a relatively low cost, this can break - the server's normal work, because the Erlang emulator has a limit on the - number of processes (32000 by default). -\end{description} - -Example: -\begin{verbatim} - {modules, - [ - ... - {mod_time, [{iqdisc, no_queue}]}, - ... - ]}. -\end{verbatim} - -\subsubsection{\option{\aname{modhostsoption}{hosts}}} -\label{sec:modhostsoption} -\ind{options!hosts} - -A module acting as a service can have one or more hostnames. These hostnames -can be defined with the \option{hosts} option. - -Examples: -\begin{itemize} -\item Serving the \ind{modules!\modecho{}}echo module on one domain: - \begin{itemize} - \item - \begin{verbatim} - {modules, - [ - ... - {mod_echo, [{hosts, ["echo.example.org"]}]}, - ... - ]}. -\end{verbatim} - \item Backwards compatibility with older \ejabberd{} versions can be retained - with: - \begin{verbatim} - {modules, - [ - ... - {mod_echo, [{host, "echo.example.org"}]}, - ... - ]}. -\end{verbatim} - \end{itemize} - \item Serving the echo module on two domains: - \begin{verbatim} - {modules, - [ - ... - {mod_echo, [{hosts, ["echo.example.net", "echo.example.com"]}]}, - ... - ]}. -\end{verbatim} -\end{itemize} - -\subsection{\aname{modannounce}{\modannounce{}}} -\label{sec: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 do these actions with their -\Jabber{} client by sending messages to specific JIDs. These JIDs are listed in -next paragraph. The first JID in each entry will apply only to the virtual host -\jid{example.org}, while the JID between brackets will apply to all virtual -hosts: -\begin{description} -\titem{example.org/announce/all (example.org/announce/all-hosts/all)} The - message is sent to all registered users. If the user is online and connected - to several resources, only the resource with the highest priority will receive - the message. If the registered user is not connected, the message will be - stored offline in assumption that \ind{modules!\modoffline{}}offline storage - (see section~\ref{sec:modoffline}) is enabled. -\titem{example.org/announce/online (example.org/announce/all-hosts/online)}The - message is sent to all connected users. If the user is online and connected - to several resources, all resources will receive the message. -\titem{example.org/announce/motd (example.org/announce/all-hosts/motd)}The - message is set as the message of the day (MOTD) and is sent to users when they - login. In addition the message is sent to all connected users (similar to - \term{announce/online}). -\titem{example.org/announce/motd/update (example.org/announce/all-hosts/motd/update)} - The message is set as message of the day (MOTD) and is sent to users when they - login. The message is \emph{not sent} to any currently connected user. -\titem{example.org/announce/motd/delete (example.org/announce/all-hosts/motd/delete)} - Any message sent to this JID removes the existing message of the day (MOTD). -\end{description} - -Options: -\begin{description} -\titem{access} \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, [{allow, admins}]}. - - {modules, - [ - ... - {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"}}. - {acl, direction, {user, "assistant", "example.org"}}. - {acl, admins, {user, "admin", "example.org"}}. - ... - {access, announce, [{allow, admins}, - {allow, direction}]}. - ... - {modules, - [ - ... - {mod_announce, [{access, announce}]}, - ... - ]}. -\end{verbatim} -\end{itemize} - -\subsection{\aname{moddisco}{\moddisco{}}} -\label{sec:moddisco} -\ind{modules!\moddisco{}}\ind{protocols!JEP-0030: Service Discovery}\ind{protocols!JEP-0011: Jabber Browsing}\ind{protocols!JEP-0094: Agent Information} - -This module adds support for Service Discovery (\jepref{0030}). With -this module enabled, services on your server can be discovered by -\Jabber{} clients. Note that \ejabberd{} has no modules with support -for the superseded Jabber Browsing (\jepref{0011}) and Agent Information -(\jepref{0094}). Accordingly, \Jabber{} clients need to have support for -the newer Service Discovery protocol if you want them be able to discover -the services you offer. - -Options: -\begin{description} -\iqdiscitem{Service Discovery (\ns{http://jabber.org/protocol/disco\#items} and - \ns{http://jabber.org/protocol/disco\#info})} -\titem{extra\_domains} \ind{options!extra\_domains}With this option, - extra domains can be added to the Service Discovery item list. -\end{description} - -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} -\end{itemize} - - -\subsection{\aname{modecho}{\modecho{}}} -\label{sec:modecho} -\ind{modules!\modecho{}}\ind{debugging} - -This module simply echoes any \Jabber{} -packet back to the sender. This mirror can be of interest for -\ejabberd{} and \Jabber{} client debugging. - -Options: -\begin{description} -\hostitem{echo} -\end{description} - -Examples: -\begin{itemize} -\item Mirror, mirror, on the wall, who is the most beautiful - of them all? - \begin{verbatim} - {modules, - [ - ... - {mod_echo, [{hosts, ["mirror.example.org"]}]}, - ... - ]}. -\end{verbatim} -\item If you still do not understand the inner workings of \modecho{}, - you can find a few more examples in section~\ref{sec:modhostsoption}. -\end{itemize} - -\subsection{\aname{modirc}{\modirc{}}} -\label{sec: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!JEP-0045: Multi-User Chat} -\begin{itemize} -\item A \Jabber{} client with `groupchat 1.0' support or Multi-User - Chat support (\jepref{0045}) is necessary to join IRC channels. -\item An IRC channel can be joined in nearly the same way as joining a - \Jabber{} Multi-User Chat room. The difference is that the room name will - be `channel\%\jid{irc.example.org}' in case \jid{irc.example.org} is - the IRC server hosting `channel'. And of course the host should point - to the IRC transport instead of the Multi-User Chat service. -\item You can register your nickame by sending `IDENTIFY password' to \\ - \jid{nickserver!irc.example.org@irc.jabberserver.org}. -\item Entering your password is possible by sending `LOGIN nick password' \\ - to \jid{nickserver!irc.example.org@irc.jabberserver.org}. -\item When using a popular \Jabber{} server, it can occur that no - connection can be achieved with some IRC servers because they limit the - number of conections from one IP. -\end{itemize} - -Options: -\begin{description} -\hostitem{irc} -\titem{access} \ind{options!access}This option can be used to specify who - may use the IRC transport (default value: \term{all}). -\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. - \begin{verbatim} - {modules, - [ - ... - {mod_irc, [{access, all}]}, - ... - ]}. -\end{verbatim} -%TODO: bug in current svn!: irc-transport.example.com will *not* show up in the -% service discovery items; instead you will see irc.example.com -\item In next example the IRC transport is available on the two virtual hosts - \jid{example.net} and \jid{example.com} with different prefixes on each host. - Moreover, the transport is only accessible by paying customers registered on - our domains and on other servers. - \begin{verbatim} - {acl, paying_customers, {user, "customer1", "example.net"}}. - {acl, paying_customers, {user, "customer2", "example.com"}}. - {acl, paying_customers, {user, "customer3", "example.org"}}. - ... - {access, paying_customers, [{allow, paying_customers}, - {deny, all}]}. - ... - {modules, - [ - ... - {mod_irc, [{access, paying_customers}, - {hosts, ["irc.example.net", "irc-transport.example.com"]}]}, - ... - ]}. -\end{verbatim} -\end{itemize} - -\subsection{\aname{modlast}{\modlast{}}} -\label{sec:modlast} -\ind{modules!\modlast{}}\ind{protocols!JEP-0012: Last Activity} - -This module adds support for Last Activity (\jepref{0012}). It can be used to -discover when a disconnected user last accessed the server, to know when a -connected user was last active on the server, or to query the uptime of the -\ejabberd{} server. - -Options: -\begin{description} -\iqdiscitem{Last activity (\ns{jabber:iq:last})} -\end{description} - -\subsection{\aname{modmuc}{\modmuc{}}} -\label{sec:modmuc} -\ind{modules!\modmuc{}}\ind{protocols!JEP-0045: Multi-User Chat}\ind{conferencing} - -With this module enabled, your server will support Multi-User Chat -(\jepref{0045}). End users will be able to join text conferences. Notice -that this module is not (yet) clusterable. - - -Some of the features of Multi-User Chat: -\begin{itemize} -\item Sending private messages to room participants. -\item Inviting users. -\item Setting a conference topic. -\item Creating password protected rooms. -\item Kicking and banning participants. -\end{itemize} - -Options: -\begin{description} -\hostitem{conference} -\titem{access} \ind{options!access}You can specify who is allowed to use - the Multi-User Chat service (by default, everyone is allowed to use it). -\titem{access\_create} \ind{options!access\_create}To configure who is - allowed to create new rooms at the Multi-User Chat service, this option - can be used (by default, everybody is allowed to create rooms). -\titem{access\_admin} \ind{options!access\_admin}This option specifies - who is allowed to administrate the Multi-User Chat service (the default - value is \term{none}, which means that only the room creator can - administer his room). By sending a message to the service JID, - administrators can send service messages that will be displayed in every - active room. -\titem{history\_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 server. -\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 \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. In this example the history - feature is disabled. - \begin{verbatim} - {acl, admins, {user, "admin", "example.org"}}. - ... - {access, muc_admins, [{allow, admins}]}. - ... - {modules, - [ - ... - {mod_muc, [{access, all}, - {access_create, all}, - {access_admin, muc_admins}, - {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"}}. - {acl, paying_customers, {user, "customer2", "example.com"}}. - {acl, paying_customers, {user, "customer3", "example.org"}}. - {acl, admins, {user, "admin", "example.org"}}. - ... - {access, muc_admins, [{allow, admins}, - {deny, all}]}. - {access, muc_access, [{allow, paying_customers}, - {allow, admins}, - {deny, all}]}. - ... - {modules, - [ - ... - {mod_muc, [{access, muc_access}, - {access_create, muc_admins}, - {access_admin, muc_admins}]}, - ... - ]}. -\end{verbatim} -\end{itemize} - -\subsection{\aname{modmuclog}{\modmuclog{}}} -\label{sec:modmuclog} -\ind{modules!\modmuclog{}} - -This module enables optional logging of Multi-User Chat (MUC) conversations to -HTML. Once you enable this module, users can join a chatroom using a MUC capable -Jabber client, and if they have enough privileges, they can request the -configuration form in which they can set the option to enable chatroom logging. - -Features: -\begin{itemize} -\item Chatroom details are added on top of each page: room title, JID, - author, subject and configuration. -\item \ind{protocols!RFC 4622: Internationalized Resource Identifiers (IRIs) and Uniform Resource Identifiers (URIs) for the Extensible Messaging and Presence Protocol (XMPP)} - Room title and JID are links to join the chatroom (using - \footahref{http://www.ietf.org/rfc/rfc4622.txt}{XMPP URIs}). -\item Subject and chatroom 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}\ind{options!access\_log} - This option restricts which users are allowed to enable or disable chatroom - 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}\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: `http://example.com/my.css'). The default value - is \term{false}. -\titem{dirtype}\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{outdir}\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{timezone}\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}\ind{options!top\_link} - With this option you can customize the link on the top right corner of each - log file. The syntax of this option is \term{\{"URL", "Text"\}}. The default - value is \term{\{"/", "Home"\}}. -\end{description} - -Examples: -\begin{itemize} -\item In the first example any chatroom owner can enable logging, and a - custom CSS file will be used (http://example.com/my.css). Further, the names - of the log files will contain the full date, and there will be no - subdirectories. The log files will be stored in /var/www/muclogs, and the - time zone will be GMT/UTC. Finally, the top link will be - \verb|<a href="http://www.jabber.ru">Jabber.ru</a>|. - \begin{verbatim} - {access, muc, [{allow, all}]}. - ... - {modules, - [ - ... - {mod_muc_log, [ - {access_log, muc}, - {cssfile, "http://example.com/my.css"}, - {dirtype, plain}, - {outdir, "/var/www/muclogs"}, - {timezone, universal}, - {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. Further, the names of the log files will only contain the day (number), - and there will be subdirectories for each year and month. The log files will - be stored in /var/www/muclogs, and the local time will be used. Finally, the - top link will be the default \verb|<a href="/">Home</a>|. - \begin{verbatim} - {acl, admins, {user, "admin1", "example.org"}}. - {acl, admins, {user, "admin2", "example.net"}}. - ... - {access, muc_log, [{allow, admins}, - {deny, all}]}. - ... - {modules, - [ - ... - {mod_muc_log, [ - {access_log, muc_log}, - {cssfile, false}, - {dirtype, subdirs}, - {outdir, "/var/www/muclogs"}, - {timezone, local} - ]}, - ... - ]}. -\end{verbatim} -\end{itemize} - -\subsection{\aname{modoffline}{\modoffline{}}} -\label{sec:modoffline} -\ind{modules!\modoffline{}} - -This module implements offline message storage. This means that all messages -sent to an offline user will be stored on the server until that user comes -online again. Thus it is very similar to how email works. Note that -\term{ejabberdctl}\ind{ejabberdctl} has a command to delete expired messages -(see section~\ref{sec:ejabberdctl}). - -\subsection{\aname{modprivacy}{\modprivacy{}}} -\label{sec:modprivacy} -\ind{modules!\modprivacy{}}\ind{Blocking Communication}\ind{Privacy Rules}\ind{protocols!RFC 3921: XMPP IM} - -This module implements Blocking Communication (also known as Privacy Rules) -as defined in section 10 from XMPP IM. If end users have support for it in -their \Jabber{} client, they will be able to: -\begin{quote} -\begin{itemize} -\item Retrieving one's privacy lists. -\item Adding, removing, and editing one's privacy lists. -\item Setting, changing, or declining active lists. -\item Setting, changing, or declining the default list (i.e., the list that - is active by default). -\item Allowing or blocking messages based on JID, group, or subscription type - (or globally). -\item Allowing or blocking inbound presence notifications based on JID, group, - or subscription type (or globally). -\item Allowing or blocking outbound presence notifications based on JID, group, - or subscription type (or globally). -\item Allowing or blocking IQ stanzas based on JID, group, or subscription type - (or globally). -\item Allowing or blocking all communications based on JID, group, or - subscription type (or globally). -\end{itemize} -(from \ahrefurl{http://www.xmpp.org/specs/rfc3921.html\#privacy}) -\end{quote} - -Options: -\begin{description} -\iqdiscitem{Blocking Communication (\ns{jabber:iq:privacy})} -\end{description} - -\subsection{\aname{modprivate}{\modprivate{}}} -\label{sec:modprivate} -\ind{modules!\modprivate{}}\ind{protocols!JEP-0049: Private XML Storage}\ind{protocols!JEP-0048: Bookmark Storage} - -This module adds support for Private XML Storage (\jepref{0049}): -\begin{quote} -Using this method, Jabber entities can store private data on the server and -retrieve it whenever necessary. The data stored might be anything, as long as -it is valid XML. One typical usage for this namespace is the server-side storage -of client-specific preferences; another is Bookmark Storage (\jepref{0048}). -\end{quote} - -Options: -\begin{description} -\iqdiscitem{Private XML Storage (\ns{jabber:iq:private})} -\end{description} - -\subsection{\aname{modpubsub}{\modpubsub{}}} -\label{sec:modpubsub} -\ind{modules!\modpubsub{}}\ind{protocols!JEP-0060: Publish-Subscribe} - -This module offers a Publish-Subscribe Service (\jepref{0060}). -Publish-Subscribe can be used to develop (examples are taken from the JEP): -\begin{quote} -\begin{itemize} -\item news feeds and content syndacation, -\item avatar management, -\item shared bookmarks, -\item auction and trading systems, -\item online catalogs, -\item workflow systems, -\item network management systems, -\item NNTP gateways, -\item vCard/profile management, -\item and weblogs. -\end{itemize} -\end{quote} - -\ind{J-EAI}\ind{EAI}\ind{ESB}\ind{Enterprise Application Integration}\ind{Enterprise Service Bus} -Another example is \footahref{http://www.process-one.net/en/projects/j-eai/}{J-EAI}. -This is an XMPP-based Enterprise Application Integration (EAI) platform (also -known as ESB, the Enterprise Service Bus). The J-EAI project builts upon -\ejabberd{}'s codebase and has contributed several features to \modpubsub{}. - -Options: -\begin{description} -\hostitem{pubsub} -\titem{served\_hosts} \ind{options!served\_hosts}To specify which hosts needs to - be served, you can use this option. If absent, only the main \ejabberd{} - host is served. % Not a straigtforward description! This needs to be improved! -\titem{access\_createnode} \ind{options!access\_createnode} - This option restricts which users are allowed to create pubsub nodes using - ACL and ACCESS. The default value is \term{pubsub\_createnode}. % Not clear enough + do not use abbreviations. -\end{description} - -Example: -\begin{verbatim} - {modules, - [ - ... - {mod_pubsub, [{served_hosts, ["example.com", - "example.org"]}, - {access_createnode, pubsub_createnode}]} - ... - ]}. -\end{verbatim} - -\subsection{\aname{modregister}{\modregister{}}} -\label{sec:modregister} -\ind{modules!\modregister{}}\ind{protocols!JEP-0077: In-Band Registration}\ind{public registration} - -This module adds support for In-Band Registration (\jepref{0077}). This protocol -enables end users to use a \Jabber{} client to: -\begin{itemize} -\item Register a new account on the server. -\item Change the password from an existing account on the server. -\item Delete an existing account on the server. -\end{itemize} - - -Options: -\begin{description} -\titem{access} \ind{options!access}This option can be configured to specify - rules to restrict registration. If a rule returns `deny' on the requested - user name, registration for that user name is dennied. (there are no - restrictions by default). -\iqdiscitem{In-Band Registration (\ns{jabber:iq:register})} -\end{description} - -Examples: -\begin{itemize} -\item Next example prohibits the registration of too short account names: -\begin{verbatim} - {acl, shortname, {user_glob, "?"}}. - {acl, shortname, {user_glob, "??"}}. - % The same using regexp: - %{acl, shortname, {user_regexp, "^..?$"}}. - ... - {access, register, [{deny, shortname}, - {allow, all}]}. - ... - {modules, - [ - ... - {mod_register, [{access, register}]}, - ... - ]}. -\end{verbatim} -\item The in-band registration of new accounts can be prohibited by changing the - \option{access} option. If you really want to disable all In-Band Registration - functionality, that is changing passwords in-band and deleting accounts - in-band, you have to remove \modregister{} from the modules list. In this - example all In-Band Registration functionality is disabled: - \begin{verbatim} - {access, register, [{deny, all}]}. - - {modules, - [ - ... -% {mod_register, [{access, register}]}, - ... - ]}. -\end{verbatim} -\end{itemize} - -\subsection{\aname{modroster}{\modroster{}}} -\label{sec:modroster} -\ind{modules!\modroster{}}\ind{roster management}\ind{protocols!RFC 3921: XMPP IM} - -This module implements roster management as defined in \footahref{http://www.xmpp.org/specs/rfc3921.html\#roster}{RFC 3921: XMPP IM}. - -Options: -\begin{description} -\iqdiscitem{Roster Management (\ns{jabber:iq:roster})} -\end{description} - -\subsection{\aname{modservicelog}{\modservicelog{}}} -\label{sec:modservicelog} -\ind{modules!\modservicelog{}}\ind{message auditing}\ind{Bandersnatch} - -This module adds support for logging end user packets via a \Jabber{} message -auditing service such as -\footahref{http://www.funkypenguin.co.za/bandersnatch/}{Bandersnatch}. All user -packets are encapsulated in a \verb|<route/>| element and sent to the specified -service(s). - -Options: -\begin{description} -\titem{loggers} \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} - -\subsection{\aname{modsharedroster}{\modsharedroster{}}} -\label{sec: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. - -Shared roster groups can be edited \emph{only} via the web interface. Each group -has a unique identification and the following parameters: -\begin{description} -\item[Name] The name of the group, which will be displayed in the roster. -\item[Description] The description of the group. This parameter does not affect - anything. -\item[Members] A list of full JIDs of group members, entered one per line in - the web interface. -\item[Displayed groups] A list of groups that will be in the rosters of this - group's members. -\end{description} - -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. Additonally, all managers should have all marketing and sales people - in their roster. Simultaneously, all marketeers and the whole sales team - should see all managers. This scenario can be achieved by creating shared - roster groups as shown in the following table: -\begin{table}[H] - \centering - \begin{tabular}{|l|l|l|l|} - \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} - -\subsection{\aname{modstats}{\modstats{}}} -\label{sec:modstats} -\ind{modules!\modstats{}}\ind{protocols!JEP-0039: Statistics Gathering}\ind{statistics} - -This module adds support for Statistics Gathering (\jepref{0039}). This protocol -allows you to retrieve next statistics from your \ejabberd{} deployment: -\begin{itemize} -\item Total number of registered users on the current virtual host (users/total). -\item Total number of registered users on all virtual hosts (users/all-hosts/total). -\item Total number of online users on the current virtual host (users/online). -\item Total number of online users on all virtual hosts (users/all-hosts/online). -\end{itemize} - -Options: -\begin{description} -\iqdiscitem{Statistics Gathering (\ns{http://jabber.org/protocol/stats})} -\end{description} - -As there are only a small amount of clients (for \ind{Tkabber}example -\footahref{http://tkabber.jabber.ru/}{Tkabber}) and software libraries with -support for this JEP, a few examples are given of the XML you need to send -in order to get the statistics. Here they are: -\begin{itemize} -\item You can request the number of online users on the current virtual host - (\jid{example.org}) by sending: - \begin{verbatim} -<iq to='example.org' type='get'> - <query xmlns='http://jabber.org/protocol/stats'> - <stat name='users/online'/> - </query> -</iq> -\end{verbatim} -\item You can request the total number of registered users on all virtual hosts - by sending: - \begin{verbatim} -<iq to='example.org' type='get'> - <query xmlns='http://jabber.org/protocol/stats'> - <stat name='users/all-hosts/total'/> - </query> -</iq> -\end{verbatim} -\end{itemize} - -\subsection{\aname{modtime}{\modtime{}}} -\label{sec:modtime} -\ind{modules!\modtime{}}\ind{protocols!JEP-0090: Entity Time} - -This module features support for Entity Time (\jepref{0090}). By using this JEP, -you are able to discover the time at another entity's location. - -Options: -\begin{description} -\iqdiscitem{Entity Time (\ns{jabber:iq:time})} -\end{description} - -\subsection{\aname{modvcard}{\modvcard{}}} -\label{sec:modvcard} -\ind{modules!\modvcard{}}\ind{JUD}\ind{Jabber User Directory}\ind{vCard}\ind{protocols!JEP-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 (\jepref{0054}). The module also -implements an uncomplicated \Jabber{} User Directory based on the vCards of -these users. Moreover, it enables the server to send its vCard when queried. - -Options: -\begin{description} -\hostitem{vjud} -\iqdiscitem{\ns{vcard-temp}} -\titem{search}\ind{options!search}This option specifies whether the search - functionality is enabled (value: \term{true}) or disabled (value: - \term{false}). If disabled, the option \term{hosts} will be ignored and the - \Jabber{} User Directory service will not appear in the Service Discovery item - list. The default value is \term{true}. -\titem{matches}\ind{options!matches}With this option, the number of reported - search results can be limited. If the option's value is set to \term{infinity}, - all search results are reported. The default value is \term{30}. -\titem{allow\_return\_all}\ind{options!allow\_return\_all}This option enables - you to specify if search operations with empty input fields should return all - users who added some information to their vCard. The default value is - \term{false}. -\titem{search\_all\_hosts}\ind{options!search\_all\_hosts}If this option is set - to \term{true}, search operations will apply to all virtual hosts. Otherwise - only the current host will be searched. The default value is \term{true}. -\end{description} - -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} - -\subsection{\aname{modvcardldap}{\modvcardldap{}}} -\label{sec:modvcardldap} -\ind{modules!\modvcardldap{}}\ind{JUD}\ind{Jabber User Directory}\ind{vCard}\ind{protocols!JEP-0054: vcard-temp} - -%TODO: verify if the referers 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{sec:ldapauth}). 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\_uidattr}, -\option{ldap\_uidattr\_format} and \option{ldap\_filter}. See -section~\ref{sec: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}\ind{options!search}This option specifies whether the search - functionality is enabled (value: \term{true}) or disabled (value: - \term{false}). If disabled, the option \term{hosts} will be ignored and the - \Jabber{} User Directory service will not appear in the Service Discovery item - list. The default value is \term{true}. -\titem{ldap\_vcard\_map}\ind{options!ldap\_vcard\_map}With this option you can - set the table that maps LDAP attributes to vCard fields. The format is: - \term{[{Name\_of\_vCard\_field, Pattern, List\_of\_LDAP\_attributes}, ...]}.\ind{protocols!RFC 2426: vCard MIME Directory Profile} - \term{Name\_of\_vcard\_field} is the type name of the vCard as defined in - \footahref{http://www.ietf.org/rfc/rfc2426.txt}{RFC 2426}. \term{Pattern} is a - string which contains pattern variables \term{"\%u"}, \term{"\%d"} or - \term{"\%s"}. \term{List\_of\_LDAP\_attributes} 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"]}, - {"FAMILY", "%s", ["sn"]}, - {"GIVEN", "%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}\ind{options!ldap\_search\_fields}This option - defines the search form and the LDAP attributes to search within. The format - is: \term{[{Name, Attribute}, ...]}. \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}\ind{options!ldap\_search\_reported}This option - defines which search fields should be reported. The format is: - \term{[{Name, vCard\_Name}, ...]}. \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{vCard\_Name} is the - vCard field name defined in the \option{ldap\_vcard\_map} option. The default - is: -\begin{verbatim} - [{"Full Name", "FN"}, - {"Given Name", "GIVEN"}, - {"Middle Name", "MIDDLE"}, - {"Family Name", "FAMILY"}, - {"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"}, - %% user's part of JID is located in the "mail" attribute - {ldap_uidattr, "mail"}, - %% common format for our emails - {ldap_uidattr_format, "%u@mail.example.org"}, - %% We have to define empty filter here, because entries in addressbook does not - %% belong to shadowAccount object class - {ldap_filter, ""}, - %% Now we want to define vCard pattern - {ldap_vcard_map, - [{"NICKNAME", "%u", []}, % just use user's part of JID as his nickname - {"GIVEN", "%s", ["givenName"]}, - {"FAMILY", "%s", ["sn"]}, - {"FN", "%s, %s", ["sn", "givenName"]}, % example: "Smith, John" - {"EMAIL", "%s", ["mail"]}, - {"BDAY", "%s", ["birthDay"]}]}, - %% Search form - {ldap_search_fields, - [{"User", "%u"}, - {"Name", "givenName"}, - {"Family Name", "sn"}, - {"Email", "mail"}, - {"Birthday", "birthDay"}]}, - %% vCard fields to be reported - %% Note that JID is always returned with search results - {ldap_search_reported, - [{"Full Name", "FN"}, - {"Nickname", "NICKNAME"}, - {"Birthday", "BDAY"}]} - ]} - ... - }. -\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", []}, - {"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} - -\subsection{\aname{modversion}{\modversion{}}} -\label{sec:modversion} -\ind{modules!\modversion{}}\ind{protocols!JEP-0092: Software Version} - -This module implements Software Version (\jepref{0092}). Consequently, it -answers \ejabberd{}'s version when queried. - -Options: -\begin{description} -\iqdiscitem{Software Version (\ns{jabber:iq:version})} -\end{description} - - -\section{\aname{initialadmin}{Creating an Initial Administrator}} -\label{sec:initialadmin} - -Before the web interface can be entered to perform administration tasks, an -account with administrator rights is needed on your \ejabberd{} deployment. - -Instructions to create an initial administrator account: -\begin{enumerate} -\item Register an account on your \ejabberd{} deployment. An account can be - created in two ways: - \begin{enumerate} - \item Using the tool \term{ejabberdctl}\ind{ejabberdctl} (see - section~\ref{sec:ejabberdctl}): - \begin{verbatim} -% ejabberdctl node@host register admin example.org password -\end{verbatim} - \item Using In-Band Registration (see section~\ref{sec:modregister}): you can - use a \Jabber{} client to register an account. - \end{enumerate} -\item Edit the configuration file to promote the account created in the previous - step to an account with administrator rights. Note that if you want to add - more administrators, a seperate acl entry is needed for each administrator. - \begin{verbatim} - {acl, admins, {user, "admin", "example.org"}}. - {access, configure, [{allow, admins}]}. -\end{verbatim} -\item Restart \ejabberd{} to load the new configuration. -\item Open the web interface (\verb|http://server:port/admin/|) in your - favourite browser. Make sure to enter the \emph{full} JID as username (in this - example: \jid{admin@example.org}. The reason that you also need to enter the - suffix, is because \ejabberd{}'s virtual hosting support. -\end{enumerate} - - -\section{\aname{onlineconfig}{Online Configuration and Monitoring}} -\label{sec:onlineconfig} - -\subsection{\aname{webinterface}{Web Interface}} -\label{sec:webinterface} -\ind{web interface} - -To perform online configuration of \ejabberd{} you need to enable the -\term{ejabberd\_http} listener with the option \term{web\_admin} (see -section~\ref{sec:listened}). Then you can open -\verb|http://server:port/admin/| in your favourite web browser. You -will be asked to enter the username (the \emph{full} \Jabber{} ID) and password -of an \ejabberd{} user with administrator rights. After authentication -you will see a page similar to figure~\ref{fig:webadmmain}. - -\begin{figure}[htbp] - \centering - \insimg{webadmmain.png} - \caption{Top page from the web interface} - \label{fig:webadmmain} -\end{figure} -Here you can edit access restrictions, manage users, create backups, -manage the database, enable/disable ports listened for, view server -statistics,\ldots - -Examples: -\begin{itemize} -\item You can serve the web interface on the same port as the - \ind{protocols!JEP-0025: HTTP Polling}HTTP Polling interface. In this example - you should point your web browser to \verb|http://example.org:5280/admin/| to - administer all virtual hosts or to - \verb|http://example.org:5280/admin/server/example.com/| to administer only - the virtual host \jid{example.com}. Before you get access to the web interface - you need to enter as username, the JID and password from a registered user - that is allowed to configure \ejabberd{}. In this example you can enter as - username `\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}. - \begin{verbatim} - ... - {acl, admins, {user, "admin", "example.net"}}. - {host_config, "example.com", [{acl, admins, {user, "admin", "example.com"}}]}. - {access, configure, [{allow, admins}]}. - ... - {hosts, ["example.org"]}. - ... - {listen, - [... - {5280, ejabberd_http, [http_poll, web_admin]}, - ... - ] - }. -\end{verbatim} -\item For security reasons, you can serve the web interface on a secured - connection, on a port differing from the HTTP Polling interface, and bind it - to the internal LAN IP. The web interface will be accessible by pointing your - web browser to \verb|https://192.168.1.1:5280/admin/|: - \begin{verbatim} - ... - {hosts, ["example.org"]}. - ... - {listen, - [... - {5270, ejabberd_http, [http_poll]}, - {5280, ejabberd_http, [web_admin, {ip, {192, 168, 1, 1}}, - tls, {certfile, "/usr/local/etc/server.pem"}]}, - ... - ] - }. -\end{verbatim} -\end{itemize} - -\subsection{\aname{ejabberdctl}{\term{ejabberdctl}}} -\label{sec:ejabberdctl} -%TODO: update when the ejabberdctl script is made more userfriendly - -It is possible to do some administration operations using the command -line tool \term{ejabberdctl}. You can list all available options by -running \term{ejabberdctl} without arguments: -\begin{verbatim} -% ejabberdctl -Usage: ejabberdctl node command - -Available commands: - status get ejabberd status - stop stop ejabberd - restart restart ejabberd - reopen-log reopen log file - register user server password register a user - unregister user server unregister a user - backup file store a database backup to file - restore file restore a database backup from file - install-fallback file install a database fallback from file - dump file dump a database to a text file - load file restore a database from a text file - import-file file import user data from jabberd 1.4 spool file - import-dir dir import user data from jabberd 1.4 spool directory - registered-users list all registered users - delete-expired-messages delete expired offline messages from database - -Example: - ejabberdctl ejabberd@host restart -\end{verbatim} - -Additional information: -\begin{description} -\titem{reopen-log } If you use a tool to rotate logs, you have to configure it - so that this command is executed after each rotation. -\titem {backup, restore, install-fallback, dump, load} You can use these - commands to create and restore backups. -%%More information about backuping can -%% be found in section~\ref{sec:backup}. -\titem{import-file, import-dir} \ind{migration from other software} - These options can be used to migrate from other \Jabber{}/XMPP servers. There - exist tutorials to \footahref{http://ejabberd.jabber.ru/migrate-to-ejabberd}{migrate from other software to ejabberd}. -\titem{delete-expired-messages} This option can be used to delete old messages - in offline storage. This might be useful when the number of offline messages - is very high. -\end{description} - - -\section{\aname{firewall}{Firewall Settings}} -\label{sec:firewall} -\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 Port& Description\\ - \hline \hline 5222& SASL and unencrypted c2s connections.\\ - \hline 5223& Obsolete SSL c2s connections.\\ - \hline 5269& s2s connections.\\ - \hline 4369& Only for clustering (see~\ref{sec:clustering}).\\ - \hline port range& Only for clustring (see~\ref{sec:clustering}). This range - is configurable (see~\ref{sec:start}).\\ - \hline - \end{tabular} -\end{table} - - -\section{\aname{srv}{SRV Records}} -\label{sec:srv} -\ind{SRV Records}\ind{clustering!SRV Records} - -\begin{itemize} -\item General information: - \footahref{http://en.wikipedia.org/wiki/SRV\_record}{SRV record} -\item Practical information: - \footahref{http://jabberd.jabberstudio.org/2/docs/section05.html\#5\_7}{Setting DNS SRV Records} -\end{itemize} - - -\section{\aname{clustering}{Clustering}} -\label{sec:clustering} -\ind{clustering} - -\subsection{\aname{howitworks}{How it Works}} -\label{sec:howitworks} -\ind{clustering!how it works} - -A \Jabber{} domain is served by one or more \ejabberd{} nodes. These nodes can -be 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} - -\subsubsection{\aname{router}{Router}} -\label{sec:router} -\ind{clustering!router} - -This module is the main router of \Jabber{} packets on each node. It -routes them based on their destination's domains. It uses a global -routing table. The domain of the packet's destination is searched in the -routing table, and if it is found, the packet is routed to the -appropriate process. If not, it is sent to the s2s manager. - -\subsubsection{\aname{localrouter}{Local Router}} -\label{sec:localrouter} -\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. - -\subsubsection{\aname{sessionmanager}{Session Manager}} -\label{sec:sessionmanager} -\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. - -\subsubsection{\aname{s2smanager}{s2s Manager}} -\label{sec:s2smanager} -\ind{clustering!s2s manager} - -This module routes packets to other \Jabber{} servers. First, it -checks if an opened s2s connection from the domain of the packet's -source to the domain of the packet's destination exists. If that is the case, -the s2s manager routes the packet to the process -serving this connection, otherwise a new connection is opened. - -\subsection{\aname{cluster}{Clustering Setup}} -\label{sec:cluster} -\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|-cookie 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 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: - -\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 interface. - - -\item Now you can add replicas of various tables to this node with - `\verb|mnesia:add_table_copy|' or - `\verb|mnesia:change_table_copy_type|' as above (just replace - `\verb|schema|' with another table name and `\verb|disc_copies|' - can be replaced with `\verb|ram_copies|' or - `\verb|disc_only_copies|'). - - Which tables to replicate is very dependant on your needs, you can get - some hints from the command `\verb|mnesia:info().|', by looking at the - size of tables and the default storage type for each table on 'first'. - - Replicating a table makes lookups in this table faster on this node. - Writing, on the other hand, will be slower. And of course if machine with one - of the replicas is down, other replicas will be used. - - Also \footahref{http://www.erlang.se/doc/doc-5.4.9/lib/mnesia-4.2.2/doc/html/Mnesia\_chap5.html\#5.3} - {section 5.3 (Table Fragmentation) of Mnesia User's Guide} can be helpful. - % The above URL needs update every Erlang release! - - (alt) Same as in previous item, but for other tables. - - -\item Run `\verb|init:stop().|' or just `\verb|q().|' to exit from - the Erlang shell. This probably can take some time if Mnesia has not yet - transfered and processed all data it needed from \term{first}. - - -\item Now run \ejabberd{} on \term{second} with almost the same config as - on \term{first} (you probably do not need to duplicate `\verb|acl|' - and `\verb|access|' options --- they will be taken from - \term{first}, and \verb|mod_muc| and \verb|mod_irc| should be - enabled only on one machine in the cluster). -\end{enumerate} - -You can repeat these steps for other machines supposed to serve this -domain. - -% TODO -% See also the section about ejabberdctl!!!! -%\section{Backup and Restore} -%\label{sec:backup} -%\ind{backup} - -\appendix{} -\section{\aname{i18nl10n}{Internationalization and Localization}} -\label{sec:i18nl10n} -\ind{xml:lang}\ind{internationalization}\ind{localization}\ind{i18n}\ind{l10n} - -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 interface also supports the \verb|Accept-Language| HTTP header (compare -figure~\ref{fig:webadmmainru} with figure~\ref{fig:webadmmain}) - -\begin{figure}[htbp] - \centering - \insimg{webadmmainru.png} - \caption{Top page from the web interface with HTTP header - `Accept-Language: ru'} - \label{fig:webadmmainru} -\end{figure} - - -%\section{\aname{ultracomplexexample}{Ultra Complex Example}} -%\label{sec:ultracomplexexample} -%TODO: a very big example covering the whole guide, with a good explanation before the example: different authenticaton mechanisms, transports, ACLs, multple virtual hosts, virtual host specific settings and general settings, modules,... - -\newpage -\section{\aname{releasenotes}{Release Notes}} -\label{sec:releasenotes} -\ind{release notes} - -\subsection{ejabberd 0.9} -\verbatiminput{release_notes_0.9.txt} - -\subsection{ejabberd 0.9.1} -\verbatiminput{release_notes_0.9.1.txt} - -\subsection{ejabberd 0.9.8} -\verbatiminput{release_notes_0.9.8.txt} - -\subsection{ejabberd 1.0.0} -\verbatiminput{release_notes_1.0.0.txt} - -\subsection{ejabberd 1.1.0} -\verbatiminput{release_notes_1.1.0.txt} - -\subsection{ejabberd 1.1.1} -\verbatiminput{release_notes_1.1.1.txt} - -\subsection{ejabberd 1.1.2} -\verbatiminput{release_notes_1.1.2.txt} - -\section{\aname{acknowledgements}{Acknowledgements}} -\label{sec: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 Michael Grigutsch (\ahrefurl{xmpp:migri@jabber.i-pobox.net}) -\item Mickael Remond (\ahrefurl{xmpp:mremond@erlang-projects.org}) -\item Sander Devrieze (\ahrefurl{xmpp:sander@devrieze.dyndns.org}) -\item Sergei Golovan (\ahrefurl{xmpp:sgolovan@nes.ru}) -\item Vsevolod Pelipas (\ahrefurl{xmpp:vsevoload@jabber.ru}) -\end{itemize} - - -\section{\aname{copyright}{Copyright Information}} -\label{sec:copyright} - -Ejabberd Installation and Operation Guide.\\ -Copyright \copyright{} January 23, 2003 --- \today{} Alexey Shchepin - -This document is free software; you can redistribute it and/or -modify it under the terms of the GNU General Public License -as published by the Free Software Foundation; either version 2 -of the License, or (at your option) any later version. - -This document is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -GNU General Public License for more details. - -You should have received a copy of the GNU General Public License along with -this document; if not, write to the Free Software Foundation, Inc., 51 Franklin -Street, Fifth Floor, Boston, MA 02110-1301, USA. - -%TODO: a glossary describing common terms -%\section{\aname{glossary}{Glossary}} -%\label{sec:glossary} -%\ind{glossary} - -%\begin{description} -%\titem{c2s} -%\titem{s2s} -%\titem{STARTTLS} -%\titem{JEP} (\Jabber{} Enhancement Proposal) -%\titem{Resource} -%\titem{Roster} -%\titem{Transport} -%\titem{JID} (\Jabber{} ID) <Wikipedia> -%\titem{JUD} (\Jabber{} User Directory) -%\titem{vCard} <Wikipedia> -%\titem{Publish-Subscribe} -%\titem{Namespace} -%\titem{Erlang} <Wikipedia> -%\titem{Fault-tolerant} -%\titem{Distributed} <Wikipedia> -%\titem{Node} <Wikipedia> -%\titem{Tuple} <Wikipedia> -%\titem{Regular Expression} -%\titem{ACL} (Access Control List) <Wikipedia> -%\titem{IPv6} <Wikipedia> -%\titem{Jabber} -%\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} |