From f89f62167124ab7e92eba22942a3fd812bea9e01 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micka=C3=ABl=20R=C3=A9mond?= Date: Mon, 28 Nov 2005 10:55:45 +0000 Subject: Documentation update SVN Revision: 445 --- doc/guide.tex | 1822 ++++++++++++++++++++++++++++++++++++++------------------- 1 file changed, 1218 insertions(+), 604 deletions(-) (limited to 'doc/guide.tex') diff --git a/doc/guide.tex b/doc/guide.tex index de5f8ede0..61965b82d 100644 --- a/doc/guide.tex +++ b/doc/guide.tex @@ -1,19 +1,27 @@ \documentclass[a4paper,10pt]{article} +%% Packages +\usepackage{float} \usepackage{graphics} \usepackage{hevea} +\usepackage[pdftex,colorlinks,unicode,urlcolor=blue,linkcolor=blue, + pdftitle=Ejabberd\ Installation\ and\ Operation\ Guide,pdfauthor=Alexey\ + Shchepin,pdfsubject=ejabberd,pdfkeywords=ejabberd, + pdfpagelabels=false]{hyperref} +\usepackage{makeidx} +%\usepackage{showidx} % Only for verifying the index entries. \usepackage{verbatim} +\usepackage{geometry} -\usepackage[twosideshift=0pt]{geometry} - -\usepackage[pdftex,colorlinks,unicode,urlcolor=blue,linkcolor=blue,pdftitle=Ejabberd\ - Installation\ and\ Operation\ Guide,pdfauthor=Alexey\ - Shchepin,pdfsubject=ejabberd,pdfkeywords=ejabberd]{hyperref} +%% Index +\makeindex +% Remove the index anchors from the HTML version to save size and bandwith. +\newcommand{\ind}[1]{\begin{latexonly}\index{#1}\end{latexonly}} +%% Images \newcommand{\logoscale}{0.7} \newcommand{\imgscale}{0.58} \newcommand{\insimg}[1]{\insscaleimg{\imgscale}{#1}} - \newcommand{\insscaleimg}[2]{ \imgsrc{#2}{} \begin{latexonly} @@ -21,8 +29,9 @@ \end{latexonly} } +%% Various \newcommand{\bracehack}{\def\{{\char"7B}\def\}{\char"7D}} - +\newcommand{\titem}[1]{\item[\bracehack\texttt{#1}]} \newcommand{\ns}[1]{\texttt{#1}} \newcommand{\jid}[1]{\texttt{#1}} \newcommand{\option}[1]{\texttt{#1}} @@ -33,6 +42,7 @@ \newcommand{\ejabberd}{\texttt{ejabberd}} \newcommand{\Jabber}{Jabber} +%% Modules \newcommand{\module}[1]{\texttt{#1}} \newcommand{\modannounce}{\module{mod\_announce}} \newcommand{\modconfigure}{\module{mod\_configure}} @@ -54,140 +64,128 @@ \newcommand{\modvcard}{\module{mod\_vcard}} \newcommand{\modversion}{\module{mod\_version}} -\newcommand{\titem}[1]{\item[\bracehack\texttt{#1}]} +%% Common options +\newcommand{\iqdiscitem}[1]{\titem{iqdisc} \ind{options!iqdisc}This specifies +the processing discipline for #1 IQ queries +(see section~\ref{sec:modiqdiscoption}).} +\newcommand{\hostitem}[1]{ + \titem{hosts} \ind{options!hosts} This option defines the hostnames of the + service (see section~\ref{sec:modhostsoption}). If neither \texttt{hosts} nor + the old \texttt{host} is present, the prefix ``\jid{#1.}'' is added to all + \ejabberd{} hostnames. +} + +%% Title page +\include{version} +\title{Ejabberd \version\ Installation and Operation Guide} +\author{Alexey Shchepin \\ + \ahrefurl{mailto:alexey@sevcom.net} \\ + \ahrefurl{xmpp:aleksey@jabber.ru}} -%\setcounter{tocdepth}{3} +%% Options +\newcommand{\marking}[1]{#1} % Marking disabled +\newcommand{\quoting}[2][yozhik]{} % Quotes disabled +\newcommand{\new}{\begin{latexonly}\marginpar{\textsc{new}}\end{latexonly}} % Highlight new features +\newcommand{\improved}{\begin{latexonly}\marginpar{\textsc{improved}}\end{latexonly}} % Highlight improved features +\newcommand{\moreinfo}[1]{} % Hide details + +%% Footnotes \begin{latexonly} \global\parskip=9pt plus 3pt minus 1pt \global\parindent=0pt - \gdef\ahrefurl#1{\href{#1}{\texttt{#1}}} \gdef\footahref#1#2{#2\footnote{\href{#1}{\texttt{#1}}}} \end{latexonly} - \newcommand{\tjepref}[2]{\footahref{http://www.jabber.org/jeps/jep-#1.html}{#2}} \newcommand{\jepref}[1]{\tjepref{#1}{JEP-#1}} -\newcommand{\iqdiscitem}[1]{\titem{iqdisc} #1 IQ queries processing -discipline (see~\ref{sec:modiqdiscoption}).} -\newcommand{\hostitem}[1]{ - \titem{host} Defines hostname of the service - (see~\ref{sec:modhostoption}). - \titem{hosts} Defines hostnames of the service - (see~\ref{sec:modhostsoption}). If neither \texttt{host} nor \texttt{hosts} - are not present, then prefix \jid{#1.} is added to all \ejabberd{} hostnames. -} - -\title{Ejabberd Installation and Operation Guide} -\author{Alexey Shchepin \\ - \ahrefurl{mailto:alexey@sevcom.net} \\ - \ahrefurl{xmpp:aleksey@jabber.ru}} -\date{July 31, 2005} - \begin{document} + +\label{sec:titlepage} \begin{titlepage} \maketitle{} - - {\centering - \insscaleimg{\logoscale}{logo.png} + + \begin{center} + {\insscaleimg{\logoscale}{logo.png} \par } -\end{titlepage} -%\newpage -\tableofcontents{} + \end{center} -\newpage -\section{Introduction} -\label{sec:intro} + \begin{quotation}\textit{I can thoroughly recommend ejabberd for ease of setup -- + Kevin Smith, Current maintainer of the Psi project}\end{quotation} -\ejabberd{} is a Free and Open Source fault-tolerant distributed \Jabber{} -server. It is written mostly in Erlang. +\end{titlepage} -The main features of \ejabberd{} are: -\begin{itemize} -\item Works on most of popular platforms: *nix (tested on Linux, FreeBSD and - NetBSD) and Win32 -\item Distributed: You can run \ejabberd{} on a cluster of machines to let all of - them serve one Jabber domain. -\item Fault-tolerance: You can setup an \ejabberd{} cluster so that all the - information required for a properly working service will be stored - permanently on more than one node. This means that if one of the nodes - crashes, then the others will continue working without disruption. - You can also add or replace nodes ``on the fly''. -\item Support for virtual hosting -\item Built-in \tjepref{0045}{Multi-User Chat} service -\item Built-in IRC transport -\item Built-in \tjepref{0060}{Publish-Subscribe} service -\item Built-in Jabber Users Directory service based on users vCards -\item Built-in web-based administration interface -\item Built-in \tjepref{0025}{HTTP Polling} service -\item SSL support -\item Support for LDAP authentication -\item Ability to interface with external components (JIT, MSN-t, Yahoo-t, etc.) -\item Migration from jabberd14 is possible -\item Mostly XMPP-compliant -\item Support for \tjepref{0030}{Service Discovery}. -\item Support for \tjepref{0039}{Statistics Gathering}. -\item Support for \ns{xml:lang} -\end{itemize} +% Set the page counter to 2 so that the titlepage and the second page do not +% have the same page number. This fixes the PDFLaTeX warning "destination with +% the same identifier". +\begin{latexonly} +\setcounter{page}{2} +\end{latexonly} -The misfeatures of \ejabberd{} are: -\begin{itemize} -\item No support for authentication and STARTTLS in S2S connections -\end{itemize} +\tableofcontents{} +% Input introduction.tex +\input{introduction} \section{Installation from Source} \label{sec:installation} +\ind{installation} \subsection{Installation Requirements} \label{sec:installreq} -\subsubsection{Unix} +\subsubsection{``Unix-like'' operating systems} \label{sec:installrequnix} +\ind{installation!requirements for ``Unix-like'' operating systems} -To compile \ejabberd{}, you will need the following packages: +To compile \ejabberd{} on a ``Unix-like'' operating system, you need: \begin{itemize} \item GNU Make; \item GCC; -\item libexpat 1.95 or later; -\item Erlang/OTP R8B or later; -\item OpenSSL 0.9.6 or later (optional). +\item libexpat 1.95 or higher; +\item Erlang/OTP R8B or higher; +\item OpenSSL 0.9.6 or higher (optional). \end{itemize} \subsubsection{Windows} \label{sec:installreqwin} +\ind{installation!requirements for Windows} -To compile \ejabberd{} in MS Windows environment, you will need the following -packages: +To compile \ejabberd{} on a Windows flavour, you need: \begin{itemize} \item MS Visual C++ 6.0 Compiler -\item \footahref{http://erlang.org/download/otp\_win32\_R10B-1a.exe}{Erlang/OTP R10B-1a} -\item \footahref{http://prdownloads.sourceforge.net/expat/expat\_win32bin\_1\_95\_7.exe?download}{Expat 1.95.7} +\item \footahref{http://erlang.org/download.html}{Erlang/OTP R8B or higher} +\item \footahref{http://sourceforge.net/project/showfiles.php?group\_id=10127\&package\_id=11277}{Expat 1.95.7 or higher} \item -\footahref{http://ftp.gnu.org/pub/gnu/libiconv/libiconv-1.9.1.tar.gz}{Iconv 1.9.1} +\footahref{http://www.gnu.org/software/libiconv/}{Iconv 1.9.1} (optional) \item \footahref{http://www.slproweb.com/products/Win32OpenSSL.html}{Shining Light OpenSSL} (to enable SSL connections) \end{itemize} - -\subsection{Obtaining} +\subsection{Obtaining \ejabberd{}} \label{sec:obtaining} -Stable \ejabberd{} release can be obtained at +\ind{download} +Released versions of \ejabberd{} can be obtained from \\ \ahrefurl{http://www.process-one.net/en/projects/ejabberd/download.html}. -The latest alpha version can be retrieved from Subversion repository\@. +\ind{Subversion repository} +The latest development version can be retrieved from the Subversion repository\@. \begin{verbatim} - svn co svn://svn.process-one.net/opt/data/svn/ejabberd/trunk ejabberd + svn co http://svn.process-one.net/ejabberd/trunk ejabberd \end{verbatim} - \subsection{Compilation} \label{sec:compilation} -\subsubsection{Unix} +\ind{compilation} + +\subsubsection{``Unix-like'' operating systems} \label{sec:compilationunix} +\ind{compilation!on ``Unix-like'' operating systems} + +Compile \ejabberd{} on a ``Unix-like'' operating system by executing: \begin{verbatim} ./configure @@ -196,50 +194,53 @@ The latest alpha version can be retrieved from Subversion repository\@. make install \end{verbatim} -This will install \ejabberd{} to \verb|/var/lib/ejabberd| directory, -\verb|ejabberd.cfg| to \verb|/etc/ejabberd| directory and create -\verb|/var/log/ejabberd| directory for log files. +These commands will: +\begin{itemize} +\item install \ejabberd{} into the directory \verb|/var/lib/ejabberd|, +\item install the configuration file into \verb|/etc/ejabberd|, +\item create a directory called \verb|/var/log/ejabberd| to store log files. +\end{itemize} \subsubsection{Windows} \label{sec:compilationwin} +\ind{compilation!on Windows} \begin{itemize} \item Install Erlang emulator (for example, into \verb|C:\Program Files\erl5.3|). \item Install Expat library into \verb|C:\Program Files\Expat-1.95.7| directory. - + Copy file \verb|C:\Program Files\Expat-1.95.7\Libs\libexpat.dll| to your Windows system directory (for example, \verb|C:\WINNT| or \verb|C:\WINNT\System32|) -\item Build and install Iconv library into \verb|C:\Program Files\iconv-1.9.1| directory. - +\item Build and install the Iconv library into the directory + \verb|C:\Program Files\iconv-1.9.1|. + Copy file \verb|C:\Program Files\iconv-1.9.1\bin\iconv.dll| to your - Windows system directory. - - Note: Instead of copying libexpat.dll and iconv.dll to Windows - directory, you can add directories + Windows system directory (more installation instructions can be found in the + file README.woe32 in the iconv distribution). + + Note: instead of copying libexpat.dll and iconv.dll to the Windows + directory, you can add the directories \verb|C:\Program Files\Expat-1.95.7\Libs| and - \verb|C:\Program Files\iconv-1.9.1\bin| to \verb|PATH| environment + \verb|C:\Program Files\iconv-1.9.1\bin| to the \verb|PATH| environment variable. -\item Being in \verb|ejabberd\src| directory run: +\item While in the directory \verb|ejabberd\src| run: \begin{verbatim} configure.bat nmake -f Makefile.win32 \end{verbatim} -\item Edit file \verb|ejabberd\src\ejabberd.cfg| and run +\item Edit the file \verb|ejabberd\src\ejabberd.cfg| and run \begin{verbatim} werl -s ejabberd -name ejabberd \end{verbatim} \end{itemize} -%\subsection{Initial Configuration} -%\label{sec:initconfig} - - \subsection{Starting} \label{sec:starting} +\ind{starting} -To start \ejabberd{}, use the following command: +Execute the following command to start \ejabberd{}: \begin{verbatim} erl -pa /var/lib/ejabberd/ebin -name ejabberd -s ejabberd \end{verbatim} @@ -247,15 +248,16 @@ or \begin{verbatim} erl -pa /var/lib/ejabberd/ebin -sname ejabberd -s ejabberd \end{verbatim} -In the latter case Erlang node will be identified using only first part of host -name, i.\,e. other Erlang nodes outside this domain can't contact this node. +In the latter case the Erlang node will be identified using only the first part +of the host name, i.\,e. other Erlang nodes outside this domain can't contact +this node. -Note that when using above command \ejabberd{} will search for config file -in current directory and will use current directory for storing user database -and logging. +Note that when using the above command, \ejabberd{} will search for the +configuration file in the current directory and will use the current directory +for storing its user database and for logging. -To specify path to config file, log files and Mnesia database directory, -you may use the following command: +To specify the path to the configuration file, the log files and the Mnesia +database directory, you may use the following command: \begin{verbatim} erl -pa /var/lib/ejabberd/ebin \ -sname ejabberd \ @@ -266,17 +268,18 @@ you may use the following command: -mnesia dir \"/var/lib/ejabberd/spool\" \end{verbatim} -You can find other useful options in Erlang manual page (\shell{erl -man erl}). +You can find other useful options in the Erlang manual page +(\shell{erl -man erl}). -To use more than 1024 connections, you should set environment variable +To use more than 1024 connections, you should set the environment variable \verb|ERL_MAX_PORTS|: \begin{verbatim} export ERL_MAX_PORTS=32000 \end{verbatim} -Note that with this value \ejabberd{} will use more memory (approximately 6MB +Note that with this value, \ejabberd{} will use more memory (approximately 6\,MB more). -To reduce memory usage, you may set environment variable +To reduce memory usage, you may set the environment variable \verb|ERL_FULLSWEEP_AFTER|: \begin{verbatim} export ERL_FULLSWEEP_AFTER=0 @@ -289,138 +292,153 @@ But in this case \ejabberd{} can start to work slower. \subsection{Initial Configuration} \label{sec:initconfig} +\ind{configuration file} -The configuration file is initially loaded the first time \ejabberd{} is -executed, when it is parsed and stored in a database. Subsequently the -configuration is loaded from the database and any commands in the configuration -file are appended to the entries in the database. The configuration file -consists of a sequence of Erlang terms. Parts of lines after \term{`\%'} sign -are ignored. Each term is tuple, where first element is name of option, and -other are option values. E.\,g.\ if this file does not contain a ``host'' -definition, then old value stored in the database will be used. +The configuration file will be loaded the first time you start \ejabberd{}. The +content from this file will be parsed and stored in a database. Subsequently the +configuration will be loaded from the database and any commands in the +configuration file are appended to the entries in the database. The +configuration file contains a sequence of Erlang terms. Lines beginning with a +\term{`\%'} sign are ignored. Each term is a tuple of which the first element is +the name of an option, and any further elements are that option's values. If the +configuration file do not contain for instance the ``hosts'' option, the old +host name(s) stored in the database will be used. -To override old values stored in the database the following lines can be added -in config: +You can override the old values stored in the database by adding next lines to +the configuration file: \begin{verbatim} override_global. override_local. override_acls. \end{verbatim} -With this lines old global or local options or ACLs will be removed before -adding new ones. - +With these lines the old global options, local options and ACLs will be removed +before new ones are added. \subsubsection{Host Names} \label{sec:confighostname} +\ind{options!hosts}\ind{host names} -Option \option{hosts} defines a list of \Jabber{} domains that \ejabberd{} -serves. E.\,g.\ to serve \jid{example.org} and \jid{example.com} domains add -the following line in the config: -\begin{verbatim} - {hosts, ["example.org", "example.com"]}. -\end{verbatim} +The option \option{hosts} defines a list containing one or more domains that +\ejabberd{} will serve. -Option \option{host} defines one \Jabber{} domain that \ejabberd{} serves. -E.\,g.\ to serve only \jid{example.org} domain add the following line in the -config: -\begin{verbatim} +Examples: +\begin{itemize} +\item Serving one domain: +\begin{itemize} +\item \begin{verbatim} + {hosts, ["example.org"]}. +\end{verbatim} +\item Backwards compatibility with older \ejabberd{} versions can be retained + with: + \begin{verbatim} {host, "example.org"}. \end{verbatim} -It have the same effect as +\end{itemize} +\item Serving two domains: \begin{verbatim} - {hosts, ["example.org"]}. + {hosts, ["one.org", "two.org"]}. \end{verbatim} - -%This option is mandatory. +\end{itemize} \subsubsection{Default Language} \label{sec:configlanguage} +\ind{options!language}\ind{language} + +The option \option{language} defines the default language of server strings that +can be seen by \Jabber{} clients. If a \Jabber{} client do not support +\option{xml:lang}, the specified language is used. The default value for the +option \option{language} is \term{"en"}. In order to take effect there must be a +translation file \term{.msg} in \ejabberd{}'s \term{msgs} directory. -Option \option{language} defines default language of \ejabberd{} messages, sent -to users. Default value is \term{"en"}. In order to take effect there must be a -translation file \term{.msg} in \ejabberd{} \term{msgs} directory. -E.\,g.\ to use Russian as default language add the following line in the config: +Examples: +\begin{itemize} +\item To set Russian as default language: \begin{verbatim} {language, "ru"}. \end{verbatim} - +\item To set Spanish as default language: +\begin{verbatim} + {language, "es"}. +\end{verbatim} +\end{itemize} \subsubsection{Access Rules} \label{sec:configaccess} +\ind{options!acl}\ind{access rules}\ind{ACL}\ind{Access Control List} -Access control in \ejabberd{} is performed via Access Control Lists (ACL). The -declarations of ACL in config file have following syntax: +Access control in \ejabberd{} is performed via Access Control Lists (ACLs). The +declarations of ACLs in the configuration file have the following syntax: \begin{verbatim} {acl, , {, ...}}. \end{verbatim} -\term{} can be one of following: +\term{} can be one of the following: \begin{description} -\titem{all} Matches all JIDs. Example: +\titem{all} Matches all JIDs. Example: \begin{verbatim} {acl, all, all}. \end{verbatim} -\titem{\{user, \}} Matches user with name - \term{} at the first virtual host. Example: +\titem{\{user, \}} Matches the user with the name + \term{} at the first virtual host. Example: \begin{verbatim} -{acl, admin, {user, "aleksey"}}. +{acl, admin, {user, "yozhik"}}. \end{verbatim} -\titem{\{user, , \}} Matches user with JID - \term{@} and any resource. Example: +\titem{\{user, , \}} Matches the user with the JID + \term{@} and any resource. Example: \begin{verbatim} -{acl, admin, {user, "aleksey", "jabber.ru"}}. +{acl, admin, {user, "yozhik", "example.org"}}. \end{verbatim} \titem{\{server, \}} Matches any JID from server - \term{}. Example: + \term{}. Example: \begin{verbatim} -{acl, jabberorg, {server, "jabber.org"}}. +{acl, exampleorg, {server, "example.org"}}. \end{verbatim} -\titem{\{user\_regexp, \}} Matches local user with name that - matches \term{} at the first virtual host. Example: +\titem{\{user\_regexp, \}} Matches any local user with a name that + matches \term{} at the first virtual host. Example: \begin{verbatim} {acl, tests, {user, "^test[0-9]*$"}}. \end{verbatim} %$ -\titem{\{user\_regexp, , \}} Matches user with name - that matches \term{} and from server \term{}. Example: +\titem{\{user\_regexp, , \}} Matches any user with a name + that matches \term{} at server \term{}. Example: \begin{verbatim} {acl, tests, {user, "^test", "example.org"}}. \end{verbatim} -\titem{\{server\_regexp, \}} Matches any JID from server that - matches \term{}. Example: +\titem{\{server\_regexp, \}} Matches any JID from the server that + matches \term{}. Example: \begin{verbatim} {acl, icq, {server, "^icq\\."}}. \end{verbatim} -\titem{\{node\_regexp, , \}} Matches user - with name that matches \term{} and from server that matches - \term{}. Example: +\titem{\{node\_regexp, , \}} Matches any user + with a name that matches \term{} at any server that matches + \term{}. Example: \begin{verbatim} -{acl, aleksey, {node_regexp, "^aleksey$", "^jabber.(ru|org)$"}}. +{acl, yohzik, {node_regexp, "^yohzik$", "^example.(com|org)$"}}. \end{verbatim} \titem{\{user\_glob, \}} \titem{\{user\_glob, , \}} \titem{\{server\_glob, \}} -\titem{\{node\_glob, , \}} This is same as - above, but uses shell glob patterns instead of regexp. These patterns can - have following special characters: +\titem{\{node\_glob, , \}} This is the same as + above. However, it uses shell glob patterns instead of regexp. These patterns + can have the following special characters: \begin{description} \titem{*} matches any string including the null string. \titem{?} matches any single character. - \titem{[...]} matches any of the enclosed characters. Character + \titem{[...]} matches any of the enclosed characters. Character ranges are specified by a pair of characters separated by a \term{`-'}. - If the first character after \term{`['} is a \term{`!'}, then any + If the first character after \term{`['} is a \term{`!'}, any character not enclosed is matched. \end{description} \end{description} The following ACLs are pre-defined: \begin{description} -\titem{all} Matches all JIDs. -\titem{none} Matches none JIDs. +\titem{all} Matches any JID. +\titem{none} Matches no JID. \end{description} -An entry allowing or denying access to different services would look similar to +An entry allowing or denying access to different services looks similar to this: \begin{verbatim} {access, , [{allow, }, @@ -429,9 +447,9 @@ this: ]}. \end{verbatim} When a JID is checked to have access to \term{}, the server -sequentially checks if this JID mathes one of the ACLs that are second elements -in each tuple in list. If it is matched, then the first element of matched -tuple is returned else ``\term{deny}'' is returned. +sequentially checks if that JID mathes any of the ACLs that are named in the +second elements of the tuples in the list. If it matches, the first element of +the first matched tuple is returned, otherwise ``\term{deny}'' is returned. Example: \begin{verbatim} @@ -440,118 +458,161 @@ Example: {allow, all}]}. \end{verbatim} -Following access rules pre-defined: +The following access rules are pre-defined: \begin{description} \titem{all} Always returns ``\term{allow}'' \titem{none} Always returns ``\term{deny}'' \end{description} - -\subsubsection{Shapers Configuration} +\subsubsection{Shapers} \label{sec:configshaper} +\ind{options!shaper}\ind{options!maxrate}\ind{shapers}\ind{maxrate}\ind{traffic speed} -With shapers is possible to bound connection traffic. The declarations of -shapers in config file have following syntax: +Shapers enable you to limit connection traffic. The syntax of +shapers is like this: \begin{verbatim} {shaper, , }. \end{verbatim} -Currently implemented only one kind of shaper: \term{maxrate}. It have +Currently only one kind of shaper called \term{maxrate} is available. It has the following syntax: \begin{verbatim} {maxrate, } \end{verbatim} -where \term{} means maximum allowed incomig rate in bytes/second. -E.\,g.\ to define shaper with name ``\term{normal}'' and maximum allowed rate -1000\,bytes/s, add following line in config: +where \term{} stands for the maximum allowed incomig rate in bytes per +second. + +Examples: +\begin{itemize} +\item To define a shaper named ``\term{normal}'' with traffic speed limited to +1,000\,bytes/second: \begin{verbatim} {shaper, normal, {maxrate, 1000}}. \end{verbatim} - +\item To define a shaper named ``\term{fast}'' with traffic speed limited to +50,000\,bytes/second: +\begin{verbatim} + {shaper, fast, {maxrate, 50000}}. +\end{verbatim} +\end{itemize} \subsubsection{Listened Sockets} \label{sec:configlistened} +\ind{options!listen} -Option \option{listen} defines list of listened sockets and what services -runned on them. Each element of list is a tuple with following elements: +The option \option{listen} defines for which addresses and ports \ejabberd{} +will listen and what services will be run on them. Each element of the list is a +tuple with the following elements: \begin{itemize} -\item Port number; -\item Module that serves this port; +\item Port number. +\item Module that serves this port. \item Options to this module. \end{itemize} -Currently these modules are implemented: -\begin{description} - \titem{ejabberd\_c2s} This module serves C2S connections. - - The following options are defined: - \begin{description} - \titem{\{access, \}} This option defines access of users - to this C2S port. Default value is ``\term{all}''. - \titem{\{shaper, \}} This option is like previous, but - use shapers instead of ``\term{allow}'' and ``\term{deny}''. Default - value is ``\term{none}''. - \titem{\{ip, IPAddress\}} This option specifies which network interface to - listen on. For example \verb|{ip, {192, 168, 1, 1}}|. - \titem{inet6} Set up the socket for IPv6. - \titem{starttls} This option specifies that STARTTLS extension is available - on connections to this port. You should also set ``\verb|certfile|'' - option. - \titem{tls} This option specifies that traffic on this port will be - encrypted using SSL immediately after connecting. You should also set - ``\verb|certfile|'' option. - \titem{ssl} This option specifies that traffic on this port will be - encrypted using SSL. You should also set ``\verb|certfile|'' option. It - is recommended to use \term{tls} option instead. - \titem{\{certfile, Path\}} Path to a file containing the SSL certificate. - \end{description} - \titem{ejabberd\_s2s\_in} This module serves incoming S2S connections. - \titem{ejabberd\_service} This module serves connections from \Jabber{} - services (i.\,e.\ that use the \ns{jabber:component:accept} namespace). - - The following additional options are defined for \term{ejabberd\_service} - (options \option{access}, \option{shaper}, \option{ip}, \option{inet6} are - still valid): - \begin{description} - \titem{\{host, Hostname, [HostOptions]\}} This option defines hostname of connected - service and allows to specify additional options, e.\,g.\ - \poption{\{password, Secret\}}. - \titem{\{hosts, [Hostnames], [HostOptions]\}} The same as above, but allows to - specify several hostnames. - \end{description} - \titem{ejabberd\_http} This module serves incoming HTTP connections. +\ind{modules!ejabberd\_c2s}\ind{modules!ejabberd\_s2s\_in}\ind{modules!ejabberd\_service}\ind{modules!ejabberd\_http}\ind{protocols!JEP-0114: Jabber Component Protocol} +Currently next modules are implemented: +\begin{table}[H] + \centering + \begin{tabular}{|l|l|l|l|l|} + \hline \texttt{ejabberd\_c2s}& Description& Handles c2s connections.\\ + \cline{2-3} & Options& \texttt{access}, \texttt{certfile}, \texttt{inet6}, + \texttt{ip}, \texttt{shaper}, \texttt{ssl}, \texttt{tls}, + \texttt{starttls},\\ + & &\texttt{starttls\_required}\\ + \hline \texttt{ejabberd\_s2s\_in}& Description& Handles incoming s2s + connections.\\ + \cline{2-3} & Options& \texttt{inet6}, \texttt{ip}\\ + \hline \texttt{ejabberd\_service}& Description& Interacts with external + components (*).\\ + \cline{2-3} & Options& \texttt{access}, \texttt{hosts}, \texttt{inet6}, + \texttt{ip}, \texttt{shaper}\\ + \hline \texttt{ejabberd\_http}& Description& Handles incoming HTTP + connections.\\ + \cline{2-3} & Options& \texttt{certfile}, \texttt{http\_poll}, + \texttt{inet6}, \texttt{ip}, \texttt{tls}, \texttt{web\_admin}\\ + \hline + \end{tabular} +\end{table} - The following options are defined: - \begin{description} - \titem{http\_poll} This option enables \jepref{0025} (HTTP Polling) - support. It is available then at \verb|http://server:port/http-poll/|. - - \titem{web\_admin} This option enables web-based interface for \ejabberd{} - administration which is available at \verb|http://server:port/admin/|, - login and password should be equal to username and password of one of - registered users who have permission defined in ``configure'' access rule. - \end{description} +(*) The mechanism for \footahref{http://ejabberd.jabber.ru/tutorials-transports}{external components} is defined in Jabber Component Protocol (\jepref{0114}). + +The following options are available: +\begin{description} + \titem{\{access, \}} \ind{options!access}This option defines + access to the port. The default value is ``\term{all}''. + \titem{\{certfile, Path\}} Path to a file containing the SSL certificate. + \titem{\{hosts, [Hostnames], [HostOptions]\}} \ind{options!hosts}This option + defines one or more hostnames of connected services and enables you to + specify additional options including \poption{\{password, Secret\}}. + \titem{http\_poll} \ind{options!http\_poll}\ind{protocols!JEP-0025: HTTP Polling}\ind{JWChat}\ind{web-based Jabber client} + This option enables HTTP Polling (\jepref{0025}) support. HTTP Polling + enables access via HTTP requests to \ejabberd{} from behind firewalls which + do not allow outgoing sockets on port 5222. + + If HTTP Polling is enabled, it will be available at + \verb|http://server:port/http-poll/|. Be aware that support for HTTP Polling + is also needed in the \Jabber{} client. Remark also that HTTP Polling can be + interesting to host a web-based \Jabber{} client such as + \footahref{http://jwchat.sourceforge.net/}{JWChat} (there is a tutorial to + \footahref{http://ejabberd.jabber.ru/jwchat}{install JWChat} with + instructions for \ejabberd{}). + \titem{inet6} \ind{options!inet6}\ind{IPv6}Set up the socket for IPv6. + \titem{\{ip, IPAddress\}} \ind{options!ip}This option specifies which network + interface to listen for. For example \verb|{ip, {192, 168, 1, 1}}|. + \titem{\{shaper, \}} \ind{options!shaper}This option defines a + shaper for the port (see section~\ref{sec:configshaper}). The default value + is ``\term{none}''. + \titem{ssl} \ind{options!ssl}\ind{SSL}This option specifies that traffic on + the port will be encrypted using SSL. You should also set the + \option{certfile} option. It is recommended to use the \term{tls} option + instead. + \titem{starttls} \ind{options!starttls}\ind{modules!STARTTLS}This option + specifies that STARTTLS encryption is available on connections to the port. + You should also set the \option{certfile} option. + \titem{starttls\_required} \ind{options!starttls\_required}This option + specifies that STARTTLS encryption is required on connections to the port. + No unencrypted connections will be allowed. You should also set the + \option{certfile} option. + \titem{tls} \ind{options!tls}\ind{TLS}This option specifies that traffic on + the port will be encrypted using SSL immediately after connecting. You + should also set the \option{certfile} option. + \titem{web\_admin} \ind{options!web\_admin}\ind{web interface}This option + enables the web interface for \ejabberd{} administration which is available + at \verb|http://server:port/admin/|. Login and password are the username and + password of one of the registered users who are granted access by the + ``configure'' access rule. \end{description} -For example, the following configuration defines that: +For instance, the following configuration defines that: \begin{itemize} -\item C2S connections are listened on port 5222 and 5223 (SSL) and denied for - user ``\term{bad}'' -\item S2S connections are listened on port 5269 -\item HTTP connections are listened on port 5280 and administration interface - and HTTP Polling support are enabled -\item All users except admins have traffic limit 1000\,B/s -\item AIM transport \jid{aim.example.org} is connected to port 5233 with - password ``\term{aimsecret}'' -\item JIT transports \jid{icq.example.org} and \jid{sms.example.org} are - connected to port 5234 with password ``\term{jitsecret}'' -\item MSN transport \jid{msn.example.org} is connected to port 5235 with - password ``\term{msnsecret}'' -\item Yahoo! transport \jid{yahoo.example.org} is connected to port 5236 with - password ``\term{yahoosecret}'' -\item Gadu-Gadu transport \jid{gg.example.org} is connected to port 5237 with - password ``\term{ggsecret}'' -\item ILE service \jid{ile.example.org} is connected to port 5238 with - password ``\term{ilesecret}'' +\item c2s connections are listened for on port 5222 and 5223 (SSL) and denied + for the user ``\term{bad}'' +\item s2s connections are listened for on port 5269 +\item Port 5280 is serving the web interface and the HTTP Polling service. Note + that it is also possible to serve them on different ports. The second + example in section~\ref{sec:webadm} shows how exactly this can be done. +\item All users except for the administrators have a traffic of limit + 1,000\,Bytes/second +\item \ind{transports!AIM}The + \footahref{http://ejabberd.jabber.ru/pyaimt}{AIM transport} + \jid{aim.example.org} is connected to port 5233 with password + ``\term{aimsecret}'' +\item \ind{transports!ICQ}The ICQ transport JIT (\jid{icq.example.org} and + \jid{sms.example.org}) is connected to port 5234 with password + ``\term{jitsecret}'' +\item \ind{transports!MSN}The + \footahref{http://ejabberd.jabber.ru/pymsnt}{MSN transport} + \jid{msn.example.org} is connected to port 5235 with password + ``\term{msnsecret}'' +\item \ind{transports!Yahoo}The + \footahref{http://ejabberd.jabber.ru/yahoo-transport-2}{Yahoo! transport} + \jid{yahoo.example.org} is connected to port 5236 with password + ``\term{yahoosecret}'' +\item \ind{transports!Gadu-Gadu}The \footahref{http://ejabberd.jabber.ru/jabber-gg-transport}{Gadu-Gadu transport} \jid{gg.example.org} is + connected to port 5237 with password ``\term{ggsecret}'' +\item \ind{transports!email notifier}The + \footahref{http://ejabberd.jabber.ru/jmc}{Jabber Mail Component} + \jid{jmc.example.org} is connected to port 5238 with password + ``\term{jmcsecret}'' \end{itemize} \begin{verbatim} {acl, blocked, {user, "bad"}}. @@ -576,13 +637,13 @@ For example, the following configuration defines that: [{password, "yahoosecret"}]}]}, {5237, ejabberd_service, [{host, "gg.example.org", [{password, "ggsecret"}]}]}, - {5238, ejabberd_service, [{host, "ile.example.org", - [{password, "ilesecret"}]}]} + {5238, ejabberd_service, [{host, "jmc.example.org", + [{password, "jmcsecret"}]}]} ] }. \end{verbatim} -Note, that for jabberd14- or wpjabberd-based services you have to make the -transports log and do XDB by themselves: +Note, that for \ind{jabberd 1.4}jabberd 1.4- or \ind{WPJabber}WPJabber-based +services you have to make the transports log and do \ind{XDB}XDB by themselves: \begin{verbatim} @@ -614,16 +675,17 @@ transports log and do XDB by themselves: \end{verbatim} - \subsubsection{Modules} \label{sec:configmodules} +\ind{modules} -Option \term{modules} defines the list of modules that will be loaded after -\ejabberd{} startup. Each list element is a tuple where first element is a -name of a module and second is list of options to this module. See -section~\ref{sec:modules} for detailed information on each module. +The option \term{modules} defines the list of modules that will be loaded after +\ejabberd{} startup. Each entry in the list is a tuple in which the first +element is the name of a module and the second is a list of options for that +module. Read section~\ref{sec:modules} for detailed information about each +module. -Example: +Example:\ind{modules!overview} \begin{verbatim} {modules, [{mod_register, []}, @@ -635,7 +697,7 @@ Example: {mod_vcard, []}, {mod_offline, []}, {mod_announce, [{access, announce}]}, - {mod_echo, [{host, "echo.example.org"}]}, + {mod_echo, [{hosts, ["echo.example.org"]}]}, {mod_private, []}, {mod_irc, []}, {mod_muc, []}, @@ -646,266 +708,415 @@ Example: ]}. \end{verbatim} - -\subsubsection{Virtual Host Configuration} +\subsubsection{Virtual Hosting} \label{sec:configvirtualhost} +\ind{virtual hosting}\ind{virtual hosts} -Options can be defined separately for different virtual hosts using -\term{host\_config} option. It have the have following syntax: +Options can be defined separately for every virtual host using the +\term{host\_config} option.\ind{options!host\_config} It has the following +syntax: \begin{verbatim} {host_config, , [