<ahref="#sec6">2.1  Installing <spanstyle="font-family:monospace">ejabberd</span> with Binary Installer</a>
</li><liclass="li-toc"><ahref="#sec7">2.2  Installing <spanstyle="font-family:monospace">ejabberd</span> with Operating System Specific Packages</a>
</li><liclass="li-toc"><ahref="#sec8">2.3  Installing <spanstyle="font-family:monospace">ejabberd</span> with CEAN</a>
</li><liclass="li-toc"><ahref="#sec9">2.4  Installing <spanstyle="font-family:monospace">ejabberd</span> from Source Code</a>
<h1id="sec2"class="chapter">Chapter 1  Introduction</h1><!--SEC END --><p>
<aid="intro"></a></p><p><spanstyle="font-family:monospace">ejabberd</span> is a free and open source instant messaging server written in <ahref="http://www.erlang.org/">Erlang/OTP</a>.</p><p><spanstyle="font-family:monospace">ejabberd</span> is cross-platform, distributed, fault-tolerant, and based on open standards to achieve real-time communication.</p><p><spanstyle="font-family:monospace">ejabberd</span> is designed to be a rock-solid and feature rich XMPP server.</p><p><spanstyle="font-family:monospace">ejabberd</span> is suitable for small deployments, whether they need to be scalable or not, as well as extremely big deployments.</p>
<!--TOC section id="sec3" Key Features-->
<h2id="sec3"class="section">1.1  Key Features</h2><!--SEC END --><p>
<aid="keyfeatures"></a>
</p><p><spanstyle="font-family:monospace">ejabberd</span> is:
</p><ulclass="itemize"><liclass="li-itemize">
Cross-platform: <spanstyle="font-family:monospace">ejabberd</span> runs under Microsoft Windows and Unix derived systems such as Linux, FreeBSD and NetBSD.</li><liclass="li-itemize">Distributed: You can run <spanstyle="font-family:monospace">ejabberd</span> on a cluster of machines and all of them will serve the same Jabber domain(s). When you need more capacity you can simply add a new cheap node to your cluster. Accordingly, you do not need to buy an expensive high-end machine to support tens of thousands concurrent users.</li><liclass="li-itemize">Fault-tolerant: You can deploy an <spanstyle="font-family:monospace">ejabberd</span> cluster so that all the information required for a properly working service will be replicated permanently on all nodes. This means that if one of the nodes crashes, the others will continue working without disruption. In addition, nodes also can be added or replaced ‘on the fly’.</li><liclass="li-itemize">Administrator Friendly: <spanstyle="font-family:monospace">ejabberd</span> is built on top of the Open Source Erlang. As a result you do not need to install an external database, an external web server, amongst others because everything is already included, and ready to run out of the box. Other administrator benefits include:
</li><liclass="li-itemize">Straightforward installers for Linux, Mac OS X, and Windows. </li><liclass="li-itemize">Web Administration.
</li><liclass="li-itemize">Shared Roster Groups.
</li><liclass="li-itemize">Command line administration tool. </li><liclass="li-itemize">Can integrate with existing authentication mechanisms.
</li><liclass="li-itemize">Capability to send announce messages.
</li></ul></li><liclass="li-itemize">Internationalized: <spanstyle="font-family:monospace">ejabberd</span> leads in internationalization. Hence it is very well suited in a globalized world. Related features are:
<ulclass="itemize"><liclass="li-itemize">
Translated to 25 languages. </li><liclass="li-itemize">Support for <ahref="http://www.ietf.org/rfc/rfc3490.txt">IDNA</a>.
</li></ul></li><liclass="li-itemize">Open Standards: <spanstyle="font-family:monospace">ejabberd</span> is the first Open Source Jabber server claiming to fully comply to the XMPP standard.
</li><liclass="li-itemize">Compressing XML streams with Stream Compression (<ahref="http://xmpp.org/extensions/xep-0138.html">XEP-0138</a>).
</li><liclass="li-itemize">Statistics via Statistics Gathering (<ahref="http://xmpp.org/extensions/xep-0039.html">XEP-0039</a>).
</li><liclass="li-itemize">IPv6 support both for c2s and s2s connections.
</li><liclass="li-itemize"><ahref="http://xmpp.org/extensions/xep-0045.html">Multi-User Chat</a> module with support for clustering and HTML logging. </li><liclass="li-itemize">Users Directory based on users vCards.
</li><liclass="li-itemize"><ahref="http://xmpp.org/extensions/xep-0060.html">Publish-Subscribe</a> component with support for <ahref="http://xmpp.org/extensions/xep-0163.html">Personal Eventing via Pubsub</a>.
</li><liclass="li-itemize">Support for web clients: <ahref="http://xmpp.org/extensions/xep-0025.html">HTTP Polling</a> and <ahref="http://xmpp.org/extensions/xep-0206.html">HTTP Binding (BOSH)</a> services.
</li><liclass="li-itemize">IRC transport.
</li><liclass="li-itemize">SIP support.
</li><liclass="li-itemize">Component support: interface with networks such as AIM, ICQ and MSN installing special tranports.
<h1id="sec5"class="chapter">Chapter 2  <ahref="#installing">Installing <spanstyle="font-family:monospace">ejabberd</span></a></h1><!--SEC END --><p><aid="installing"></a></p><p><aid="install.binary"></a></p>
<!--TOC section id="sec6" Installing <span style="font-family:monospace">ejabberd</span> with Binary Installer-->
<h2id="sec6"class="section">2.1  <ahref="#install.binary">Installing <spanstyle="font-family:monospace">ejabberd</span> with Binary Installer</a></h2><!--SEC END --><p><aid="install.binary"></a></p><p>Probably the easiest way to install an <spanstyle="font-family:monospace">ejabberd</span> instant messaging server
The binary installers of released <spanstyle="font-family:monospace">ejabberd</span> versions
are available in the ProcessOne <spanstyle="font-family:monospace">ejabberd</span> downloads page:
<ahref="http://www.process-one.net/en/ejabberd/downloads"><spanstyle="font-family:monospace">http://www.process-one.net/en/ejabberd/downloads</span></a></p><p>The installer will deploy and configure a full featured <spanstyle="font-family:monospace">ejabberd</span>
server and does not require any extra dependencies.</p><p>In *nix systems, remember to set executable the binary installer before starting it. For example:
and ’stop’ in the ’bin’ directory where <spanstyle="font-family:monospace">ejabberd</span> is installed.</p><p>The Windows installer also adds ejabberd as a system service,
and for example it doesn’t read the file ejabberdctl.cfg.</p><p>On a *nix system, if you want ejabberd to be started as daemon at boot time,
copy <spanstyle="font-family:monospace">ejabberd.init</span> from the ’bin’ directory to something like <spanstyle="font-family:monospace">/etc/init.d/ejabberd</span>
Create a system user called <spanstyle="font-family:monospace">ejabberd</span>,
give it write access to the directories <spanstyle="font-family:monospace">database/</span> and <spanstyle="font-family:monospace">logs/</span>, and set that as home;
Then you can call <spanstyle="font-family:monospace">/etc/inid.d/ejabberd start</span> as root to start the server.</p><p>When ejabberd is started, the processes that are started in the system
are <spanstyle="font-family:monospace">beam</span> or <spanstyle="font-family:monospace">beam.smp</span>, and also <spanstyle="font-family:monospace">epmd</span>.
In Microsoft Windows, the processes are <spanstyle="font-family:monospace">erl.exe</span> and <spanstyle="font-family:monospace">epmd.exe</span>.
For more information regarding <spanstyle="font-family:monospace">epmd</span> consult the section <ahref="#epmd">5.2</a>.</p><p>If <spanstyle="font-family:monospace">ejabberd</span> doesn’t start correctly in Windows,
Then uninstall <spanstyle="font-family:monospace">ejabberd</span> and install it again.</p><p>If <spanstyle="font-family:monospace">ejabberd</span> doesn’t start correctly and a crash dump is generated,
and can identify what is exactly the problem.</p><p>The <spanstyle="font-family:monospace">ejabberdctl</span> administration script is included in the <spanstyle="font-family:monospace">bin</span> directory.
Please refer to the section <ahref="#ejabberdctl">4.1</a> for details about <spanstyle="font-family:monospace">ejabberdctl</span>,
and configurable options to fine tune the Erlang runtime system.</p><p><aid="install.os"></a></p>
<!--TOC section id="sec7" Installing <span style="font-family:monospace">ejabberd</span> with Operating System Specific Packages-->
<h2id="sec7"class="section">2.2  <ahref="#install.os">Installing <spanstyle="font-family:monospace">ejabberd</span> with Operating System Specific Packages</a></h2><!--SEC END --><p><aid="install.os"></a></p><p>Some Operating Systems provide a specific <spanstyle="font-family:monospace">ejabberd</span> package adapted to
resources provided by your Operating System for more information.</p><p>Usually those packages create a script like <spanstyle="font-family:monospace">/etc/init.d/ejabberd</span>
to start and stop <spanstyle="font-family:monospace">ejabberd</span> as a service at boot time.</p><p><aid="install.cean"></a></p>
<!--TOC section id="sec8" Installing <span style="font-family:monospace">ejabberd</span> with CEAN-->
<h2id="sec8"class="section">2.3  <ahref="#install.cean">Installing <spanstyle="font-family:monospace">ejabberd</span> with CEAN</a></h2><!--SEC END --><p><aid="install.cean"></a></p><p><ahref="http://cean.process-one.net/">CEAN</a>
alternative to the binary installer and Operating System’s <spanstyle="font-family:monospace">ejabberd</span> packages.</p><p>You will have to create your own <spanstyle="font-family:monospace">ejabberd</span> start
The default <spanstyle="font-family:monospace">ejabberdctl</span> script is located
into <spanstyle="font-family:monospace">ejabberd</span>’s priv directory and can be used as an example.</p><p><aid="installation"></a></p>
<!--TOC section id="sec9" Installing <span style="font-family:monospace">ejabberd</span> from Source Code-->
<h2id="sec9"class="section">2.4  <ahref="#installation">Installing <spanstyle="font-family:monospace">ejabberd</span> from Source Code</a></h2><!--SEC END --><p><aid="installation"></a>
</p><p>The canonical form for distribution of <spanstyle="font-family:monospace">ejabberd</span> stable releases is the source code package.
Compiling <spanstyle="font-family:monospace">ejabberd</span> from source code is quite easy in *nix systems,
as long as your system have all the dependencies.</p><p><aid="installreq"></a></p>
<!--TOC subsection id="sec10" Requirements-->
<h3id="sec10"class="subsection">2.4.1  <ahref="#installreq">Requirements</a></h3><!--SEC END --><p><aid="installreq"></a>
</p><p>To compile <spanstyle="font-family:monospace">ejabberd</span> on a ‘Unix-like’ operating system, you need:
</li><liclass="li-itemize">Libexpat 1.95 or higher
</li><liclass="li-itemize">Erlang/OTP R15B or higher.
</li><liclass="li-itemize">Libyaml 1.4 or higher
</li><liclass="li-itemize">OpenSSL 0.9.8 or higher, for STARTTLS, SASL and SSL encryption.
</li><liclass="li-itemize">Zlib 1.2.3 or higher, for Stream Compression support (<ahref="http://xmpp.org/extensions/xep-0138.html">XEP-0138</a>). Optional.
</li><liclass="li-itemize">PAM library. Optional. For Pluggable Authentication Modules (PAM). See section <ahref="#pam">3.1.5</a>.
</li><liclass="li-itemize">GNU Iconv 1.8 or higher, for the IRC Transport (mod_irc). Optional. Not needed on systems with GNU Libc. See section <ahref="#modirc">3.3.8</a>.
</li><liclass="li-itemize">ImageMagick’s Convert program. Optional. For CAPTCHA challenges. See section <ahref="#captcha">3.1.9</a>.
</li><liclass="li-itemize">exmpp 0.9.6 or higher. Optional. For import/export user data with <ahref="http://xmpp.org/extensions/xep-0227.html">XEP-0227</a> XML files.
<h3id="sec11"class="subsection">2.4.2  <ahref="#download">Download Source Code</a></h3><!--SEC END --><p><aid="download"></a>
</p><p>Released versions of <spanstyle="font-family:monospace">ejabberd</span> are available in the ProcessOne <spanstyle="font-family:monospace">ejabberd</span> downloads page:
the <spanstyle="font-family:monospace">make install</span> command.<p></p></dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">--enable-user[=USER]</span></span></dt><ddclass="dd-description">
<spanstyle="font-family:monospace">/var/lib/ejabberd/</span> will be used by default.<p></p></dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">--enable-pam</span></span></dt><ddclass="dd-description">
Enable the PAM authentication method (see section <ahref="#pam">3.1.5</a>).<p></p></dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">--enable-mssql</span></span></dt><ddclass="dd-description">
See section <ahref="#database">3.2</a> for more information.</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">--enable-tools</span></span></dt><ddclass="dd-description">
Enable the use of development tools.</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">--enable-mysql</span></span></dt><ddclass="dd-description">
Enable MySQL support (see section <ahref="#odbc">3.2.1</a>).</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">--enable-pgsql</span></span></dt><ddclass="dd-description">
Enable PostgreSQL support (see section <ahref="#odbc">3.2.1</a>).</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">--enable-zlib</span></span></dt><ddclass="dd-description">
Enable Stream Compression (XEP-0138) using zlib.</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">--enable-stun</span></span></dt><ddclass="dd-description">
Enable STUN/TURN support (see section <ahref="#stun">3.1.10</a>).</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">--enable-iconv</span></span></dt><ddclass="dd-description">
Enable iconv support. This is needed for <spanstyle="font-family:monospace">mod_irc</span> (see seciont <ahref="#modirc">3.3.8</a>).</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">--enable-debug</span></span></dt><ddclass="dd-description">
Compile with <spanstyle="font-family:monospace">+debug_info</span> enabled.<p></p></dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">--enable-full-xml</span></span></dt><ddclass="dd-description">
Use this option only if you are sure your XMPP clients include a fully compliant XML parser.<p></p></dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">--disable-transient-supervisors</span></span></dt><ddclass="dd-description">
Disable the use of Erlang/OTP supervision for transient processes.<p></p></dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">--enable-nif</span></span></dt><ddclass="dd-description">
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">ejabberdctl.cfg</span></span></dt><ddclass="dd-description"> Configuration file of the administration script
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">inetrc</span></span></dt><ddclass="dd-description"> Network DNS configuration file
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">lib/</span></span></dt><ddclass="dd-description"> Binary system libraries (*.so)
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">/sbin/ejabberdctl</span></span></dt><ddclass="dd-description"> Administration script (see section <ahref="#ejabberdctl">4.1</a>)
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">/share/doc/ejabberd/</span></span></dt><ddclass="dd-description"> Documentation of ejabberd
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">/var/log/ejabberd/</span></span></dt><ddclass="dd-description"> Log directory (see section <ahref="#logfiles">7.1</a>):
<dlclass="description"><dtclass="dt-description">
<spanstyle="font-weight:bold"><spanstyle="font-family:monospace">ejabberd.log</span></span></dt><ddclass="dd-description"> ejabberd service log
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">erlang.log</span></span></dt><ddclass="dd-description"> Erlang/OTP system log
</dd></dl>
</dd></dl><p><aid="start"></a></p>
<!--TOC subsection id="sec14" Start-->
<h3id="sec14"class="subsection">2.4.5  <ahref="#start">Start</a></h3><!--SEC END --><p><aid="start"></a>
</p><p>You can use the <spanstyle="font-family:monospace">ejabberdctl</span> command line administration script to start and stop <spanstyle="font-family:monospace">ejabberd</span>.
If you provided the configure option <spanstyle="font-family:monospace">--enable-user=USER</span> (see <ahref="#compile">2.4.3</a>),
you can execute <spanstyle="font-family:monospace">ejabberdctl</span> with either that system account or root.</p><p>Usage example:
and can identify what is exactly the problem.</p><p>Please refer to the section <ahref="#ejabberdctl">4.1</a> for details about <spanstyle="font-family:monospace">ejabberdctl</span>,
and configurable options to fine tune the Erlang runtime system.</p><p>If you want ejabberd to be started as daemon at boot time,
copy <spanstyle="font-family:monospace">ejabberd.init</span> to something like <spanstyle="font-family:monospace">/etc/init.d/ejabberd</span>
<!--TOC subsection id="sec17" Specific Notes for Microsoft Windows-->
<h3id="sec17"class="subsection">2.4.8  <ahref="#windows">Specific Notes for Microsoft Windows</a></h3><!--SEC END --><p><aid="windows"></a>
</p><p><aid="windowsreq"></a></p>
<!--TOC subsubsection id="sec18" Requirements-->
<h4id="sec18"class="subsubsection"><ahref="#windowsreq">Requirements</a></h4><!--SEC END --><p><aid="windowsreq"></a></p><p>To compile <spanstyle="font-family:monospace">ejabberd</span> on a Microsoft Windows system, you need:
</li><liclass="li-itemize"><ahref="http://www.zlib.net/">Zlib 1.2.3 or higher</a>
</li></ul><p><aid="windowscom"></a></p>
<!--TOC subsubsection id="sec19" Compilation-->
<h4id="sec19"class="subsubsection"><ahref="#windowscom">Compilation</a></h4><!--SEC END --><p><aid="windowscom"></a></p><p>We assume that we will try to put as much library as possible into <code>C:\sdk\</code> to make it easier to track what is install for <spanstyle="font-family:monospace">ejabberd</span>.</p><olclass="enumerate"type=1><liclass="li-enumerate">
Install Erlang emulator (for example, into <code>C:\sdk\erl5.5.5</code>).
</li><liclass="li-enumerate">Install Expat library into <code>C:\sdk\Expat-2.0.0</code>
</p></li><liclass="li-enumerate">Install OpenSSL in <code>C:\sdk\OpenSSL</code> and add <code>C:\sdk\OpenSSL\lib\VC</code> to your path or copy the binaries to your system directory.
</li><liclass="li-enumerate">Install ZLib in <code>C:\sdk\gnuWin32</code>. Copy
<code>C:\sdk\GnuWin32\bin\zlib1.dll</code> to your system directory. If you change your path it should already be set after libiconv install.
</li><liclass="li-enumerate">Make sure the you can access Erlang binaries from your path. For example: <code>set PATH=%PATH%;"C:\sdk\erl5.6.5\bin"</code>
</li><liclass="li-enumerate">Depending on how you end up actually installing the library you might need to check and tweak the paths in the file configure.erl.
</li><liclass="li-enumerate">While in the directory <code>ejabberd\src</code> run:
<!--TOC section id="sec20" Create an XMPP Account for Administration-->
<h2id="sec20"class="section">2.5  <ahref="#initialadmin">Create an XMPP Account for Administration</a></h2><!--SEC END --><p><aid="initialadmin"></a></p><p>You need an XMPP account and grant him administrative privileges
to enter the <spanstyle="font-family:monospace">ejabberd</span> Web Admin:
Register an XMPP account on your <spanstyle="font-family:monospace">ejabberd</span> server, for example <spanstyle="font-family:monospace">admin1@example.org</span>.
</pre></li><liclass="li-enumerate">Using an XMPP client and In-Band Registration (see section <ahref="#modregister">3.3.19</a>).
</li></ol>
</li><liclass="li-enumerate">Edit the <spanstyle="font-family:monospace">ejabberd</span> configuration file to give administration rights to the XMPP account you created:
<h2id="sec21"class="section">2.6  <ahref="#upgrade">Upgrading <spanstyle="font-family:monospace">ejabberd</span></a></h2><!--SEC END --><p><aid="upgrade"></a></p><p>To upgrade an ejabberd installation to a new version,
and Mnesia database spool directory are not removed.</p><p><spanstyle="font-family:monospace">ejabberd</span> automatically updates the Mnesia table definitions at startup when needed.
<h1id="sec22"class="chapter">Chapter 3  <ahref="#configure">Configuring <spanstyle="font-family:monospace">ejabberd</span></a></h1><!--SEC END --><p><aid="configure"></a>
</p><p><aid="basicconfig"></a></p>
<!--TOC section id="sec23" Basic Configuration-->
<h2id="sec23"class="section">3.1  <ahref="#basicconfig">Basic Configuration</a></h2><!--SEC END --><p><aid="basicconfig"></a></p><p>The configuration file will be loaded the first time you start <spanstyle="font-family:monospace">ejabberd</span>.
to differentiate between the new and legacy file formats (see section <ahref="#oldconfig">3.1.1</a>).</p><p>Note that <spanstyle="font-family:monospace">ejabberd</span> never edits the configuration file.</p><p>The configuration file is written in
to convert it to the new YAML format using <spanstyle="font-family:monospace">convert_to_yaml</span> command
from <spanstyle="font-family:monospace">ejabberdctl</span> (see <ahref="#ejabberdctl">4.1</a> and <ahref="#list-eja-commands">4.2.1</a> for details).</p><p><aid="hostnames"></a></p>
<!--TOC subsection id="sec25" Host Names-->
<h3id="sec25"class="subsection">3.1.2  <ahref="#hostnames">Host Names</a></h3><!--SEC END --><p><aid="hostnames"></a>
</p><p>The option <spanstyle="font-family:monospace">hosts</span> defines a list containing one or more domains that
<spanstyle="font-family:monospace">ejabberd</span> will serve.</p><p>The syntax is:
To accomplish that, instead of defining each option in <spanstyle="font-family:monospace">host_config</span>
use <spanstyle="font-family:monospace">append_host_config</span> with the same syntax.</p><p>In this example three virtual hosts have some similar modules, but there are also
<h3id="sec27"class="subsection">3.1.4  <ahref="#listened">Listening Ports</a></h3><!--SEC END --><p><aid="listened"></a>
</p><p>The option <spanstyle="font-family:monospace">listen</span> defines for which ports, addresses and network protocols <spanstyle="font-family:monospace">ejabberd</span>
<!--TOC subsubsection id="sec28" Port Number, IP Address and Transport Protocol-->
<h4id="sec28"class="subsubsection"><ahref="#listened-port">Port Number, IP Address and Transport Protocol</a></h4><!--SEC END --><p><aid="listened-port"></a></p><p>The port number defines which port to listen for incoming connections.
<h4id="sec30"class="subsubsection"><ahref="#listened-options">Options</a></h4><!--SEC END --><p><aid="listened-options"></a></p><p>This is a detailed description of each option allowed by the listening modules:
<spanstyle="font-weight:bold"><spanstyle="font-family:monospace">access: AccessName</span></span></dt><ddclass="dd-description"> This option defines
access to the port. The default value is <spanstyle="font-family:monospace">all</span>.
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">backlog: Value</span></span></dt><ddclass="dd-description"> The backlog value
Simple web page that allows a user to fill a CAPTCHA challenge (see section <ahref="#captcha">3.1.9</a>).
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">certfile: Path</span></span></dt><ddclass="dd-description"> Full path to a file containing the default SSL certificate.
To define a certificate file specific for a given domain, use the global option <spanstyle="font-family:monospace">domain_certfile</span>.
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">ciphers: Ciphers</span></span></dt><ddclass="dd-description"> OpenSSL ciphers list in the same format accepted by
List of general options relating to SSL/TLS. These map to <code><a href="https://www.openssl.org/docs/ssl/SSL_CTX_set_options.html">OpenSSL's set_options()</a></code>.
For a full list of options available in ejabberd, <code><a href="https://github.com/processone/tls/blob/master/c_src/options.h">see the source</a></code>.
This option enables HTTP Binding (<ahref="http://xmpp.org/extensions/xep-0124.html">XEP-0124</a> and <ahref="http://xmpp.org/extensions/xep-0206.html">XEP-0206</a>) support. HTTP Bind
enables access via HTTP requests to <spanstyle="font-family:monospace">ejabberd</span> from behind firewalls which
do not allow outgoing sockets on port 5222.<p>Remember that you must also install and enable the module mod_http_bind.</p><p>If HTTP Bind is enabled, it will be available at
<code>http://server:port/http-bind/</code>. Be aware that support for HTTP Bind
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">request_handlers: {Path: Module}</span></span></dt><ddclass="dd-description"> To define one or several handlers that will serve HTTP requests.
For example, if you want <spanstyle="font-family:monospace">mod_foo</span> to serve the URIs that start with <spanstyle="font-family:monospace">/a/b/</span>,
and you also want <spanstyle="font-family:monospace">mod_http_bind</span> to serve the URIs <spanstyle="font-family:monospace">/http-bind/</span>,
The default value is <spanstyle="font-family:monospace">true</span>, to be compliant with <ahref="http://xmpp.org/extensions/xep-0114.html">XEP-0114</a>.
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">shaper: none|ShaperName</span></span></dt><ddclass="dd-description"> This option defines a
shaper for the port (see section <ahref="#shapers">3.1.7</a>). The default value
is <spanstyle="font-family:monospace">none</span>.
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">shaper_rule: none|ShaperRule</span></span></dt><ddclass="dd-description"> This option defines a
shaper rule for the <spanstyle="font-family:monospace">ejabberd_service</span> (see section <ahref="#shapers">3.1.7</a>). The recommended value
is <spanstyle="font-family:monospace">fast</span>.
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">starttls: true|false</span></span></dt><ddclass="dd-description"> This option
You should also set the <spanstyle="font-family:monospace">certfile</span> option.
You can define a certificate file for a specific domain using the global option <spanstyle="font-family:monospace">domain_certfile</span>.
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">starttls_required: true|false</span></span></dt><ddclass="dd-description"> This option
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">tls: true|false</span></span></dt><ddclass="dd-description"> This option specifies that traffic on
Whether to enable or disable TLS compression. The default value is <spanstyle="font-family:monospace">true</span>.
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">trusted_proxies: all | [IpString]</span></span></dt><ddclass="dd-description">
Specify what proxies are trusted when an HTTP request contains the header <spanstyle="font-family:monospace">X-Forwarded-For</span>
You can specify <spanstyle="font-family:monospace">all</span> to allow all proxies, or specify a list of IPs in string format.
The default value is: <spanstyle="font-family:monospace">["127.0.0.1"]</span>
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">web_admin: true|false</span></span></dt><ddclass="dd-description"> This option
enables the Web Admin for <spanstyle="font-family:monospace">ejabberd</span> administration which is available
at <code>http://server:port/admin/</code>. Login and password are the username and
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">zlib: true|false</span></span></dt><ddclass="dd-description"> This
option specifies that Zlib stream compression (as defined in <ahref="http://xmpp.org/extensions/xep-0138.html">XEP-0138</a>)
</dd></dl><p>There are some additional global options that can be specified in the ejabberd configuration file (outside <spanstyle="font-family:monospace">listen</span>):
The default value is to not use STARTTLS: <spanstyle="font-family:monospace">false</span>.
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">s2s_certfile: Path</span></span></dt><ddclass="dd-description"> Full path to a
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">s2s_ciphers: Ciphers</span></span></dt><ddclass="dd-description"> OpenSSL ciphers list
in the same format accepted by ‘<code>openssl ciphers</code>’ command.
List of general options relating to SSL/TLS. These map to <code><a href="https://www.openssl.org/docs/ssl/SSL_CTX_set_options.html">OpenSSL's set_options()</a></code>.
For a full list of options available in ejabberd, <code><a href="https://github.com/processone/tls/blob/protocol_options/c_src/options.h">see the source</a></code>.
<h4id="sec31"class="subsubsection"><ahref="#listened-examples">Examples</a></h4><!--SEC END --><p><aid="listened-examples"></a></p><p>For example, the following simple configuration defines:
</p><ulclass="itemize"><liclass="li-itemize">
There are three domains. The default certificate file is <spanstyle="font-family:monospace">server.pem</span>.
However, the c2s and s2s connections to the domain <spanstyle="font-family:monospace">example.com</span> use the file <spanstyle="font-family:monospace">example_com.pem</span>.
</li><liclass="li-itemize">Port 5222 listens for c2s connections with STARTTLS,
</li><liclass="li-itemize">The <ahref="http://www.ejabberd.im/jabber-gg-transport">Gadu-Gadu transport</a><spanstyle="font-family:monospace">gg.example.org</span> is
connected to port 5237 with password ‘<spanstyle="font-family:monospace">ggsecret</span>’.
</li><liclass="li-itemize">The
<ahref="http://www.ejabberd.im/jmc">Jabber Mail Component</a>
<spanstyle="font-family:monospace">jmc.example.org</span> is connected to port 5238 with password
</li><liclass="li-itemize">The service custom has enabled the special option to avoiding checking the <spanstyle="font-family:monospace">from</span> attribute in the packets send by this component. The component can send packets in behalf of any users from the server, or even on behalf of any server.
</p><dlclass="description"><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">[Method, ...]</span></span></dt></dl><p>The following authentication methods are supported by <spanstyle="font-family:monospace">ejabberd</span>:
</p><ulclass="itemize"><liclass="li-itemize">
internal (default) — See section <ahref="#internalauth">3.1.5</a>.
</li><liclass="li-itemize">external — See section <ahref="#extauth">3.1.5</a>.
</li><liclass="li-itemize">ldap — See section <ahref="#ldap">3.2.2</a>.
</li><liclass="li-itemize">odbc — See section <ahref="#odbc">3.2.1</a>.
</li><liclass="li-itemize">anonymous — See section <ahref="#saslanonymous">3.1.5</a>.
</li><liclass="li-itemize">pam — See section <ahref="#pam">3.1.5</a>.
</li></ul><p>Account creation is only supported by internal, external and odbc methods.</p><p>The option <spanstyle="font-family:monospace">resource_conflict</span> defines the action when a client attempts to
The default value is <spanstyle="font-family:monospace">closeold</span>.
If the client uses old Jabber Non-SASL authentication (<ahref="http://xmpp.org/extensions/xep-0078.html">XEP-0078</a>),
then this option is not respected, and the action performed is <spanstyle="font-family:monospace">closeold</span>.</p><p>The option <spanstyle="font-family:monospace">fqdn</span> allows you to define the Fully Qualified Domain Name
<h4id="sec33"class="subsubsection"><ahref="#internalauth">Internal</a></h4><!--SEC END --><p><aid="internalauth"></a>
</p><p><spanstyle="font-family:monospace">ejabberd</span> uses its internal Mnesia database as the default authentication method.
The value <spanstyle="font-family:monospace">internal</span> will enable the internal authentication method.</p><p>The option <spanstyle="font-family:monospace">auth_password_format: plain|scram</span>
the old Jabber Non-SASL (<ahref="http://xmpp.org/extensions/xep-0078.html">XEP-0078</a>), <spanstyle="font-family:monospace">SASL PLAIN</span>,
<spanstyle="font-family:monospace">SASL DIGEST-MD5</span>, and <spanstyle="font-family:monospace">SASL SCRAM-SHA-1</span>.</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">scram</span></span></dt><ddclass="dd-description">
for this reason, when this value is configured it cannot be changed to <spanstyle="font-family:monospace">plain</span> anymore.
This format allows clients to authenticate using: <spanstyle="font-family:monospace">SASL PLAIN</span> and <spanstyle="font-family:monospace">SASL SCRAM-SHA-1</span>.
</dd></dl><p>Examples:
</p><ulclass="itemize"><liclass="li-itemize">
To use internal authentication on <spanstyle="font-family:monospace">example.org</span> and LDAP
authentication on <spanstyle="font-family:monospace">example.net</span>:
The script must be executable by ejabberd.</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">extauth_instances: Integer</span></span></dt><ddclass="dd-description">
The default value is the minimum number: 1.</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">extauth_cache: false|CacheTimeInteger</span></span></dt><ddclass="dd-description">
The value <spanstyle="font-family:monospace">false</span> disables the caching feature, this is the default.
The integer <spanstyle="font-family:monospace">0</span> (zero) enables caching for statistics, but doesn’t use that cached information to authenticate users.
<spanstyle="font-weight:bold"><spanstyle="font-family:monospace">Anonymous login:</span></span></dt><ddclass="dd-description"> This is a standard login, that use the
clients</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">SASL Anonymous:</span></span></dt><ddclass="dd-description"> This is a special SASL authentication
</dd></dl><p>The anonymous authentication method can be configured with the following
options. Remember that you can use the <spanstyle="font-family:monospace">host_config</span> option to set virtual
host specific options (see section <ahref="#virtualhost">3.1.3</a>).</p><dlclass="description"><dtclass="dt-description">
<spanstyle="font-weight:bold"><spanstyle="font-family:monospace">allow_multiple_connections: false|true</span></span></dt><ddclass="dd-description"> This option is only used
<spanstyle="font-weight:bold"><spanstyle="font-family:monospace">pam_service: Name</span></span></dt><ddclass="dd-description">This option defines the PAM service name.
Default is <spanstyle="font-family:monospace">"ejabberd"</span>. Refer to the PAM documentation of your operation system
version, you can <spanstyle="font-family:monospace">kill(1)</span><spanstyle="font-family:monospace">epam</span> process periodically to reduce its memory
consumption: <spanstyle="font-family:monospace">ejabberd</span> will restart this process immediately.
</li><liclass="li-itemize"><spanstyle="font-family:monospace">epam</span> program tries to turn off delays on authentication failures.
</p><dlclass="description"><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">acl: { ACLName: { ACLType: ACLValue } }</span></span></dt></dl><p><spanstyle="font-family:monospace">ACLType: ACLValue</span> can be one of the following:
</pre></dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">user: Username</span></span></dt><ddclass="dd-description"> Matches the user with the name
<spanstyle="font-family:monospace">Username</span> at the first virtual host. Example:
</pre></dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">user: {Username: Server}</span></span></dt><ddclass="dd-description"> Matches the user with the JID
<spanstyle="font-family:monospace">Username@Server</span> and any resource. Example:
</pre></dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">server: Server</span></span></dt><ddclass="dd-description"> Matches any JID from server
</pre></dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">resource: Resource</span></span></dt><ddclass="dd-description"> Matches any JID with a resource
</pre></dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">shared_group: Groupname</span></span></dt><ddclass="dd-description"> Matches any member of a Shared Roster Group with name <spanstyle="font-family:monospace">Groupname</span> in the virtual host. Example:
</pre></dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">shared_group: {Groupname: Server}</span></span></dt><ddclass="dd-description"> Matches any member of a Shared Roster Group with name <spanstyle="font-family:monospace">Groupname</span> in the virtual host <spanstyle="font-family:monospace">Server</span>. Example:
</pre></dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">ip: Network</span></span></dt><ddclass="dd-description"> Matches any IP address from the <spanstyle="font-family:monospace">Network</span>. Example:
</pre></dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">user_regexp: Regexp</span></span></dt><ddclass="dd-description"> Matches any local user with a name that
matches <spanstyle="font-family:monospace">Regexp</span> on local virtual hosts. Example:
</pre></dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">user_regexp: {Regexp: Server}</span></span></dt><ddclass="dd-description"> Matches any user with a name
that matches <spanstyle="font-family:monospace">Regexp</span> at server <spanstyle="font-family:monospace">Server</span>. Example:
</pre></dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">server_regexp: Regexp</span></span></dt><ddclass="dd-description"> Matches any JID from the server that
</pre></dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">resource_regexp: Regexp</span></span></dt><ddclass="dd-description"> Matches any JID with a resource that
</pre></dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">node_regexp: {UserRegexp: ServerRegexp}</span></span></dt><ddclass="dd-description"> Matches any user
with a name that matches <spanstyle="font-family:monospace">UserRegexp</span> at any server that matches
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">node_glob: {UserGlob: ServerGlob}</span></span></dt><ddclass="dd-description"> This is the same as
<spanstyle="font-weight:bold"><spanstyle="font-family:monospace">*</span></span></dt><ddclass="dd-description"> matches any string including the null string.
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">?</span></span></dt><ddclass="dd-description"> matches any single character.
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">[...]</span></span></dt><ddclass="dd-description"> matches any of the enclosed characters. Character
ranges are specified by a pair of characters separated by a <spanstyle="font-family:monospace">‘-’</span>.
If the first character after <spanstyle="font-family:monospace">‘[’</span> is a <spanstyle="font-family:monospace">‘!’</span>, any
<spanstyle="font-weight:bold"><spanstyle="font-family:monospace">all</span></span></dt><ddclass="dd-description"> Matches any JID.
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">none</span></span></dt><ddclass="dd-description"> Matches no JID.
</dd></dl><p><aid="AccessRights"></a></p>
<!--TOC subsubsection id="sec39" Access Rights-->
<h4id="sec39"class="subsubsection"><ahref="#AccessRights">Access Rights</a></h4><!--SEC END --><p><aid="AccessRights"></a>
</p><p>An entry allowing or denying access to different services.
</p><dlclass="description"><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">access: { AccessName: { ACLName: allow|deny } }</span></span></dt></dl><p>When a JID is checked to have access to <spanstyle="font-family:monospace">Accessname</span>, the server
<spanstyle="font-weight:bold"><spanstyle="font-family:monospace">all</span></span></dt><ddclass="dd-description"> Always returns the value ‘<spanstyle="font-family:monospace">allow</span>’.
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">none</span></span></dt><ddclass="dd-description"> Always returns the value ‘<spanstyle="font-family:monospace">deny</span>’.
</dd></dl><p><aid="configmaxsessions"></a></p>
<!--TOC subsubsection id="sec40" Limiting Opened Sessions with ACL-->
<h4id="sec40"class="subsubsection"><ahref="#configmaxsessions">Limiting Opened Sessions with ACL</a></h4><!--SEC END --><p><aid="configmaxsessions"></a>
</p><p>The special access <spanstyle="font-family:monospace">max_user_sessions</span> specifies the maximum
can be either a number, or <spanstyle="font-family:monospace">infinity</span>. The default value is
<spanstyle="font-family:monospace">infinity</span>.</p><p>The syntax is:
</p><dlclass="description"><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">{ max_user_sessions: { ACLName: MaxNumber } }</span></span></dt></dl><p>This example limits the number of sessions per user to 5 for all users, and to 10 for admins:
<!--TOC subsubsection id="sec41" Several connections to a remote XMPP server with ACL-->
<h4id="sec41"class="subsubsection"><ahref="#configmaxs2sconns">Several connections to a remote XMPP server with ACL</a></h4><!--SEC END --><p><aid="configmaxs2sconns"></a>
</p><p>The special access <spanstyle="font-family:monospace">max_s2s_connections</span> specifies how many
<spanstyle="font-family:monospace">xml:lang</span>, the specified language is used.</p><p>The option syntax is:
</p><dlclass="description"><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">language: Language</span></span></dt></dl><p>The default value is <spanstyle="font-family:monospace">en</span>.
<spanstyle="font-family:monospace">Language.msg</span> in <spanstyle="font-family:monospace">ejabberd</span>’s <spanstyle="font-family:monospace">msgs</span> directory.</p><p>For example, to set Russian as default language:
</p><preclass="verbatim">language: "ru"
</pre><p>Appendix <ahref="#i18ni10n">A</a> provides more details about internationalization and localization.</p><p><aid="captcha"></a></p>
<!--TOC subsection id="sec44" CAPTCHA-->
<h3id="sec44"class="subsection">3.1.9  <ahref="#captcha">CAPTCHA</a></h3><!--SEC END --><p><aid="captcha"></a>
</p><p>Some <spanstyle="font-family:monospace">ejabberd</span> modules can be configured to require a CAPTCHA challenge on certain actions.
If the client does not support CAPTCHA Forms (<ahref="http://xmpp.org/extensions/xep-0158.html">XEP-0158</a>),
a web link is provided so the user can fill the challenge in a web browser.</p><p>An example script is provided that generates the image
using ImageMagick’s Convert program.</p><p>The configurable options are:
The URL sent to the user is formed by: <spanstyle="font-family:monospace">Protocol://Host:Port/captcha/</span>
The default value is: protocol <spanstyle="font-family:monospace">http</span>, the first hostname configured, and port <spanstyle="font-family:monospace">80</span>.
</dd></dl><p>Additionally, an <spanstyle="font-family:monospace">ejabberd_http</span> listener must be enabled with the <spanstyle="font-family:monospace">captcha</span> option.
See section <ahref="#listened-module">3.1.4</a>.</p><p>Example configuration:
<h3id="sec45"class="subsection">3.1.10  <ahref="#stun">STUN and TURN</a></h3><!--SEC END --><p><aid="stun"></a>
</p><p><spanstyle="font-family:monospace">ejabberd</span> is able to act as a stand-alone STUN/TURN server
(<ahref="http://tools.ietf.org/html/rfc5389">RFC 5389</a>/<ahref="http://tools.ietf.org/html/rfc5766">RFC 5766</a>). In that role <spanstyle="font-family:monospace">ejabberd</span> helps clients with ICE (<ahref="http://tools.ietf.org/html/rfc5245">RFC 5245</a>) or Jingle ICE (<ahref="http://xmpp.org/extensions/xep-0176.html">XEP-0176</a>) support to discover their external addresses and ports and to relay media traffic when it is impossible to establish direct
peer-to-peer connection.</p><p>You should configure <spanstyle="font-family:monospace">ejabberd_stun</span> listening module as described in <ahref="#listened">3.1.4</a> section.
<h3id="sec46"class="subsection">3.1.11  <ahref="#sip">SIP</a></h3><!--SEC END --><p><aid="sip"></a>
</p><p><spanstyle="font-family:monospace">ejabberd</span> has built-in SIP support. In order to activate it you need to add
listeners for it, configure DNS properly and enable <spanstyle="font-family:monospace">mod_sip</span> for
the desired virtual host.</p><p>To add a listener you should configure <spanstyle="font-family:monospace">ejabberd_sip</span> listening module as
described in <ahref="#listened">3.1.4</a> section. If option <spanstyle="font-family:monospace">tls</span> is specified, option
<spanstyle="font-family:monospace">certfile</span> must be specified as well, otherwise incoming TLS connections would fail.</p><p>Example configuration with standard ports
(as per <ahref="http://tools.ietf.org/html/rfc3261">RFC 3261</a>):
</p><preclass="verbatim">listen:
...
-
port: 5060
transport: udp
module: ejabberd_sip
-
port: 5060
module: ejabberd_sip
-
port: 5061
module: ejabberd_sip
tls: true
certfile: "/etc/ejabberd/server.pem"
...
</pre><p>Note that there is no StartTLS support in SIP and <ahref="http://en.wikipedia.org/wiki/Server_Name_Indication">SNI</a> support is somewhat tricky, so for TLS you have to configure
different virtual hosts on different ports if you have different certificate files for them.</p><p>Next you need to configure DNS SIP records for your virtual domains.
Refer to <ahref="http://tools.ietf.org/html/rfc3263">RFC 3263</a> for the detailed explanation.
Simply put, you should add NAPTR and SRV records for your domains.
Skip NAPTR configuration if your DNS provider doesn’t support this type of records.
It’s not fatal, however, highly recommended.</p><p>Example configuration of NAPTR records:
</p><preclass="verbatim">example.com IN NAPTR 10 0 "s" "SIPS+D2T" "" _sips._tcp.example.com.
example.com IN NAPTR 20 0 "s" "SIP+D2T" "" _sip._tcp.example.com.
example.com IN NAPTR 30 0 "s" "SIP+D2U" "" _sip._udp.example.com.
</pre><p>Example configuration of SRV records with standard ports
(as per <ahref="http://tools.ietf.org/html/rfc3261">RFC 3261</a>):
</p><preclass="verbatim">_sip._udp IN SRV 0 0 5060 sip.example.com.
_sip._tcp IN SRV 0 0 5060 sip.example.com.
_sips._tcp IN SRV 0 0 5061 sip.example.com.
</pre><p><aid="includeconfigfile"></a></p>
<!--TOC subsection id="sec47" Include Additional Configuration Files-->
<h3id="sec47"class="subsection">3.1.12  <ahref="#includeconfigfile">Include Additional Configuration Files</a></h3><!--SEC END --><p><aid="includeconfigfile"></a>
</p><p>The option <spanstyle="font-family:monospace">include_config_file</span> in a configuration file instructs <spanstyle="font-family:monospace">ejabberd</span> to include other configuration files immediately.</p><p>The basic syntax is:
</p><dlclass="description"><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">include_config_file: { Filename: [Suboption, ...] }</span></span></dt></dl><p>The filename can be indicated either as an absolute path,
or relative to the main <spanstyle="font-family:monospace">ejabberd</span> configuration file.
<spanstyle="font-weight:bold"><spanstyle="font-family:monospace">disallow: [Optionname, ...]</span></span></dt><ddclass="dd-description"> Disallows the usage of those options in the included configuration file.
The default value is an empty list: <spanstyle="font-family:monospace">[]</span>
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">allow_only: [Optionname, ...]</span></span></dt><ddclass="dd-description"> Allows only the usage of those options in the included configuration file.
<!--TOC subsection id="sec48" Option Macros in Configuration File-->
<h3id="sec48"class="subsection">3.1.13  <ahref="#optionmacros">Option Macros in Configuration File</a></h3><!--SEC END --><p><aid="optionmacros"></a>
</p><p>In the <spanstyle="font-family:monospace">ejabberd</span> configuration file,
and later use this macro when defining an option.</p><p>A macro is defined with this syntax:
</p><dlclass="description"><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">define_macro: { ’MACRO’: Value }</span></span></dt></dl><p>
The <spanstyle="font-family:monospace">MACRO</span> must be surrounded by single quotation marks,
</pre><p>The resulting option interpreted by <spanstyle="font-family:monospace">ejabberd</span> is: <spanstyle="font-family:monospace">loglevel: 5</span>.</p><p>This example shows that values can be any arbitrary Erlang term:
different storage systems for modules, and so forth.</p><p>The following databases are supported by <spanstyle="font-family:monospace">ejabberd</span>:
<h3id="sec50"class="subsection">3.2.1  <ahref="#odbc">ODBC</a></h3><!--SEC END --><p><aid="odbc"></a></p><p>The actual database access is defined in the options with <spanstyle="font-family:monospace">odbc_</span> prefix. The
<spanstyle="font-weight:bold"><spanstyle="font-family:monospace">odbc_type: mysql | pgsql | odbc</span></span></dt><ddclass="dd-description"> The type of an ODBC connection.
The default is <spanstyle="font-family:monospace">odbc</span>.
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">odbc_server: String</span></span></dt><ddclass="dd-description"> A hostname of the ODBC server. The default is
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">odbc_port: Port</span></span></dt><ddclass="dd-description"> The port where the ODBC server is accepting connections.
The option is only valid for <spanstyle="font-family:monospace">mysql</span> and <spanstyle="font-family:monospace">pgsql</span>. The default is
<spanstyle="font-family:monospace">3306</span> and <spanstyle="font-family:monospace">5432</span> respectively.
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">odbc_database: String</span></span></dt><ddclass="dd-description"> The database name. The default is <spanstyle="font-family:monospace">‘‘ejabberd’’</span>.
The option is only valid for <spanstyle="font-family:monospace">mysql</span> and <spanstyle="font-family:monospace">pgsql</span>.
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">odbc_username: String</span></span></dt><ddclass="dd-description"> The username. The default is <spanstyle="font-family:monospace">‘‘ejabberd’’</span>.
The option is only valid for <spanstyle="font-family:monospace">mysql</span> and <spanstyle="font-family:monospace">pgsql</span>.
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">odbc_password: String</span></span></dt><ddclass="dd-description"> The password. The default is empty string.
The option is only valid for <spanstyle="font-family:monospace">mysql</span> and <spanstyle="font-family:monospace">pgsql</span>.
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">odbc_pool_size: N</span></span></dt><ddclass="dd-description"> By default <spanstyle="font-family:monospace">ejabberd</span> opens 10 connections to
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">odbc_keepalive_interval: N</span></span></dt><ddclass="dd-description"> You can configure an interval to
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">odbc_start_interval: N</span></span></dt><ddclass="dd-description"> If the connection to the database fails,
<spanstyle="font-family:monospace">ejabberd</span> waits 30 seconds before retrying.
<h4id="sec53"class="subsubsection"><ahref="#ldapconnection">Connection</a></h4><!--SEC END --><p><aid="ldapconnection"></a></p><p>Two connections are established to the LDAP server per vhost,
one for authentication and other for regular calls.</p><p>Parameters:
<spanstyle="font-weight:bold"><spanstyle="font-family:monospace">ldap_servers: [Servers, ...]</span></span></dt><ddclass="dd-description"> List of IP addresses or DNS names of your
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">ldap_encrypt: none|tls</span></span></dt><ddclass="dd-description"> Type of connection encryption to the LDAP server.
When <spanstyle="font-family:monospace">hard</span> is enabled <spanstyle="font-family:monospace">ejabberd</span> doesn’t proceed if a certificate is invalid.
When <spanstyle="font-family:monospace">soft</span> is enabled <spanstyle="font-family:monospace">ejabberd</span> proceeds even if check fails.
The default is <spanstyle="font-family:monospace">false</span> which means no checks are performed.
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">ldap_port: Number</span></span></dt><ddclass="dd-description"> Port to connect to your LDAP server.
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">ldap_rootdn: RootDN</span></span></dt><ddclass="dd-description"> Bind DN. The default value
is <spanstyle="font-family:monospace">""</span> which means ‘anonymous connection’.
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">ldap_password: Password</span></span></dt><ddclass="dd-description"> Bind password. The default
value is <spanstyle="font-family:monospace">""</span>.
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">ldap_deref_aliases: never|always|finding|searching</span></span></dt><ddclass="dd-description"> Whether or not to dereference aliases. The default is <spanstyle="font-family:monospace">never</span>.
<h4id="sec54"class="subsubsection"><ahref="#ldapauth">Authentication</a></h4><!--SEC END --><p><aid="ldapauth"></a></p><p>You can authenticate users against an LDAP directory.
Note that current LDAP implementation does not support SASL authentication.</p><p>Available options are:</p><dlclass="description"><dtclass="dt-description">
<spanstyle="font-weight:bold"><spanstyle="font-family:monospace">ldap_base: Base</span></span></dt><ddclass="dd-description">LDAP base directory which stores
The values for <spanstyle="font-family:monospace">ldap_uidattr</span> and
<spanstyle="font-family:monospace">ldap_uidattr_format</span> are described as follow:
<dlclass="description"><dtclass="dt-description">
<spanstyle="font-weight:bold"><spanstyle="font-family:monospace">ldap_uidattr</span></span></dt><ddclass="dd-description">LDAP attribute which holds
the user’s part of a JID. The default value is <spanstyle="font-family:monospace">"uid"</span>.
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">ldap_uidattr_format</span></span></dt><ddclass="dd-description">Format of
the <spanstyle="font-family:monospace">ldap_uidattr</span> variable. The format <em>must</em> contain one and
only one pattern variable <spanstyle="font-family:monospace">"%u"</span> which will be replaced by the
user’s part of a JID. For example, <spanstyle="font-family:monospace">"%u@example.org"</span>. The default
value is <spanstyle="font-family:monospace">"%u"</span>.
when you are unable to define all filter rules in <spanstyle="font-family:monospace">ldap_filter</span>. You
can define <spanstyle="font-family:monospace">"%u"</span>, <spanstyle="font-family:monospace">"%d"</span>, <spanstyle="font-family:monospace">"%s"</span> and <spanstyle="font-family:monospace">"%D"</span> pattern
variables in Filter: <spanstyle="font-family:monospace">"%u"</span> is replaced by a user’s part of a JID,
<spanstyle="font-family:monospace">"%d"</span> is replaced by the corresponding domain (virtual host),
all <spanstyle="font-family:monospace">"%s"</span> variables are consecutively replaced by values of FilterAttrs
attributes and <spanstyle="font-family:monospace">"%D"</span> is replaced by Distinguished Name. By default
<spanstyle="font-family:monospace">ldap_dn_filter</span> is undefined.
<h4id="sec55"class="subsubsection"><ahref="#ldapexamples">Examples</a></h4><!--SEC END --><p><aid="ldapexamples"></a></p><p><aid="ldapcommonexample"></a></p>
<!--TOC paragraph id="sec56" Common example-->
<h5id="sec56"class="paragraph"><ahref="#ldapcommonexample">Common example</a></h5><!--SEC END --><p><aid="ldapcommonexample"></a></p><p>Let’s say <spanstyle="font-family:monospace">ldap.example.org</span> is the name of our LDAP server. We have
users with their passwords in <spanstyle="font-family:monospace">"ou=Users,dc=example,dc=org"</span> directory.
</pre><p>Now we want to use users LDAP-info as their vCards. We have four attributes
defined in our LDAP schema: <spanstyle="font-family:monospace">"mail"</span>— email address, <spanstyle="font-family:monospace">"givenName"</span>
— first name, <spanstyle="font-family:monospace">"sn"</span>— second name, <spanstyle="font-family:monospace">"birthDay"</span>— birthday.
Also we want users to search each other. Let’s see how we can set it up:</p><preclass="verbatim">modules:
</pre></li><liclass="li-itemize">In the second example the modules <spanstyle="font-family:monospace">mod_echo</span>, <spanstyle="font-family:monospace">mod_time</span>, and
<spanstyle="font-family:monospace">mod_version</span> are loaded without options.
<h3id="sec59"class="subsection">3.3.1  <ahref="#modoverview">Modules Overview</a></h3><!--SEC END --><p><aid="modoverview"></a>
</p><p>The following table lists all modules included in <spanstyle="font-family:monospace">ejabberd</span>.</p><blockquoteclass="table"><divclass="center"><divclass="center"><hrstyle="width:80%;height:2"></div>
<tr><tdstyle="text-align:left;border:solid 1px;white-space:nowrap"><ahref="#modhttpbind"><spanstyle="font-family:monospace">mod_http_bind</span></a></td><tdstyle="text-align:left;border:solid 1px;white-space:nowrap">XMPP over Bosh service (HTTP Binding)</td><tdstyle="text-align:left;border:solid 1px;white-space:nowrap"> </td></tr>
<tr><tdstyle="text-align:left;border:solid 1px;white-space:nowrap"><ahref="#modpubsub"><spanstyle="font-family:monospace">mod_pubsub</span></a></td><tdstyle="text-align:left;border:solid 1px;white-space:nowrap">Pub-Sub (<ahref="http://xmpp.org/extensions/xep-0060.html">XEP-0060</a>), PEP (<ahref="http://xmpp.org/extensions/xep-0163.html">XEP-0163</a>)</td><tdstyle="text-align:left;border:solid 1px;white-space:nowrap"><spanstyle="font-family:monospace">mod_caps</span></td></tr>
<tr><tdstyle="text-align:left;border:solid 1px;white-space:nowrap"><ahref="#modpubsub"><spanstyle="font-family:monospace">mod_pubsub_odbc</span></a></td><tdstyle="text-align:left;border:solid 1px;white-space:nowrap">Pub-Sub (<ahref="http://xmpp.org/extensions/xep-0060.html">XEP-0060</a>), PEP (<ahref="http://xmpp.org/extensions/xep-0163.html">XEP-0163</a>)</td><tdstyle="text-align:left;border:solid 1px;white-space:nowrap">supported DB (*) and <spanstyle="font-family:monospace">mod_caps</span></td></tr>
<tr><tdstyle="text-align:left;border:solid 1px;white-space:nowrap"><ahref="#modservicelog"><spanstyle="font-family:monospace">mod_service_log</span></a></td><tdstyle="text-align:left;border:solid 1px;white-space:nowrap">Copy user messages to logger service</td><tdstyle="text-align:left;border:solid 1px;white-space:nowrap"> </td></tr>
your own risk!</p><p><aid="modcommonoptions"></a></p>
<!--TOC subsection id="sec60" Common Options-->
<h3id="sec60"class="subsection">3.3.2  <ahref="#modcommonoptions">Common Options</a></h3><!--SEC END --><p><aid="modcommonoptions"></a></p><p>The following options are used by many modules. Therefore, they are described in
this separate section.</p><p><aid="modiqdiscoption"></a></p>
<h4id="sec61"class="subsubsection"><ahref="#modiqdiscoption"><spanstyle="font-family:monospace">iqdisc</span></a></h4><!--SEC END --><p><aid="modiqdiscoption"></a>
</p><p>Many modules define handlers for processing IQ queries of different namespaces
to this server or to a user (e. g. to <spanstyle="font-family:monospace">example.org</span> or to
<spanstyle="font-family:monospace">user@example.org</span>). This option defines processing discipline for
<spanstyle="font-weight:bold"><spanstyle="font-family:monospace">no_queue</span></span></dt><ddclass="dd-description"> All queries of a namespace with this processing discipline are
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">one_queue</span></span></dt><ddclass="dd-description"> In this case a separate queue is created for the processing
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">N</span></span></dt><ddclass="dd-description"> N separate queues are created to process the
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">parallel</span></span></dt><ddclass="dd-description"> For every packet with this discipline a separate Erlang process
<h4id="sec62"class="subsubsection"><ahref="#modhostoption"><spanstyle="font-family:monospace">host</span></a></h4><!--SEC END --><p><aid="modhostoption"></a>
</p><p>This option defines the Jabber ID of a service provided by an <spanstyle="font-family:monospace">ejabberd</span> module.</p><p>The syntax is:
</p><dlclass="description"><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">host: HostName</span></span></dt></dl><p>If you include the keyword "@HOST@" in the HostName,
it is replaced at start time with the real virtual host string.</p><p>This example configures
<h3id="sec63"class="subsection">3.3.3  <ahref="#modannounce"><spanstyle="font-family:monospace">mod_announce</span></a></h3><!--SEC END --><p><aid="modannounce"></a>
</p><p>This module enables configured users to broadcast announcements and to set
or sending messages to specific JIDs.</p><p>The Ad-hoc commands are listed in the Server Discovery.
For this feature to work, <spanstyle="font-family:monospace">mod_adhoc</span> must be enabled.</p><p>The specific JIDs where messages can be sent are listed bellow.
<spanstyle="font-weight:bold"><spanstyle="font-family:monospace">example.org/announce/all (example.org/announce/all-hosts/all)</span></span></dt><ddclass="dd-description"> The
If <spanstyle="font-family:monospace">odbc</span> value is defined, make sure you have defined the database, see <ahref="#database">3.2</a>.
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">access: AccessName</span></span></dt><ddclass="dd-description"> This option specifies who is allowed to
<h3id="sec64"class="subsection">3.3.4  <ahref="#moddisco"><spanstyle="font-family:monospace">mod_disco</span></a></h3><!--SEC END --><p><aid="moddisco"></a>
<spanstyle="font-weight:bold"><spanstyle="font-family:monospace">iqdisc: Discipline</span></span></dt><ddclass="dd-description"> This specifies
the processing discipline for Service Discovery (<spanstyle="font-family:monospace">http://jabber.org/protocol/disco#items</span> and
<spanstyle="font-family:monospace">http://jabber.org/protocol/disco#info</span>) IQ queries (see section <ahref="#modiqdiscoption">3.3.2</a>).
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">extra_domains: [Domain, ...]</span></span></dt><ddclass="dd-description"> With this option,
Any arbitrary <spanstyle="font-family:monospace">Name</span> and <spanstyle="font-family:monospace">URL</span> can be specified, not only contact addresses.
</dd></dl><p>Examples:
</p><ulclass="itemize"><liclass="li-itemize">
To serve a link to the Jabber User Directory on <spanstyle="font-family:monospace">jabber.org</span>:
<h3id="sec65"class="subsection">3.3.5  <ahref="#modecho"><spanstyle="font-family:monospace">mod_echo</span></a></h3><!--SEC END --><p><aid="modecho"></a>
<spanstyle="font-weight:bold"><spanstyle="font-family:monospace">host: HostName</span></span></dt><ddclass="dd-description"> This option defines the Jabber ID of the
service. If the <spanstyle="font-family:monospace">host</span> option is not specified, the Jabber ID will be the
hostname of the virtual host with the prefix ‘<spanstyle="font-family:monospace">echo.</span>’. The keyword "@HOST@"
<h3id="sec66"class="subsection">3.3.6  <ahref="#modhttpbind"><spanstyle="font-family:monospace">mod_http_bind</span></a></h3><!--SEC END --><p><aid="modhttpbind"></a>
</p><p>This module implements XMPP over Bosh (formerly known as HTTP Binding)
as defined in <ahref="http://xmpp.org/extensions/xep-0124.html">XEP-0124</a> and <ahref="http://xmpp.org/extensions/xep-0206.html">XEP-0206</a>.
<h3id="sec67"class="subsection">3.3.7  <ahref="#modhttpfileserver"><spanstyle="font-family:monospace">mod_http_fileserver</span></a></h3><!--SEC END --><p><aid="modhttpfileserver"></a>
</p><p>This simple module serves files from the local disk over HTTP.</p><p>Options:
<h3id="sec68"class="subsection">3.3.8  <ahref="#modirc"><spanstyle="font-family:monospace">mod_irc</span></a></h3><!--SEC END --><p><aid="modirc"></a>
</p><p>This module is an IRC transport that can be used to join channels on IRC
be ‘channel%<spanstyle="font-family:monospace">irc.example.org</span>’ in case <spanstyle="font-family:monospace">irc.example.org</span> is
<spanstyle="font-weight:bold"><spanstyle="font-family:monospace">host: HostName</span></span></dt><ddclass="dd-description"> This option defines the Jabber ID of the
service. If the <spanstyle="font-family:monospace">host</span> option is not specified, the Jabber ID will be the
hostname of the virtual host with the prefix ‘<spanstyle="font-family:monospace">irc.</span>’. The keyword "@HOST@"
If <spanstyle="font-family:monospace">odbc</span> value is defined, make sure you have defined the database, see <ahref="#database">3.2</a>.
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">access: AccessName</span></span></dt><ddclass="dd-description"> This option can be used to specify who
may use the IRC transport (default value: <spanstyle="font-family:monospace">all</span>).
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">default_encoding: Encoding</span></span></dt><ddclass="dd-description"> Set the default IRC encoding.
</pre></li><liclass="li-itemize">In next example the IRC transport is available with JIDs with prefix <spanstyle="font-family:monospace">irc-t.net</span>.
<h3id="sec69"class="subsection">3.3.9  <ahref="#modlast"><spanstyle="font-family:monospace">mod_last</span></a></h3><!--SEC END --><p><aid="modlast"></a>
</p><p>This module adds support for Last Activity (<ahref="http://xmpp.org/extensions/xep-0012.html">XEP-0012</a>). It can be used to
<spanstyle="font-weight:bold"><spanstyle="font-family:monospace">iqdisc: Discipline</span></span></dt><ddclass="dd-description"> This specifies
the processing discipline for Last activity (<spanstyle="font-family:monospace">jabber:iq:last</span>) IQ queries (see section <ahref="#modiqdiscoption">3.3.2</a>).
<h3id="sec70"class="subsection">3.3.10  <ahref="#modmuc"><spanstyle="font-family:monospace">mod_muc</span></a></h3><!--SEC END --><p><aid="modmuc"></a>
</p><p>This module provides a Multi-User Chat (<ahref="http://xmpp.org/extensions/xep-0045.html">XEP-0045</a>) service.
<spanstyle="font-weight:bold"><spanstyle="font-family:monospace">host: HostName</span></span></dt><ddclass="dd-description"> This option defines the Jabber ID of the
service. If the <spanstyle="font-family:monospace">host</span> option is not specified, the Jabber ID will be the
hostname of the virtual host with the prefix ‘<spanstyle="font-family:monospace">conference.</span>’. The keyword "@HOST@"
If <spanstyle="font-family:monospace">odbc</span> value is defined, make sure you have defined the database, see <ahref="#database">3.2</a>.
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">access: AccessName</span></span></dt><ddclass="dd-description"> You can specify who is allowed to use
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">access_create: AccessName</span></span></dt><ddclass="dd-description"> To configure who is
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">access_persistent: AccessName</span></span></dt><ddclass="dd-description"> To configure who is
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">access_admin: AccessName</span></span></dt><ddclass="dd-description"> This option specifies
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">history_size: Size</span></span></dt><ddclass="dd-description"> A small history of
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">max_users: Number</span></span></dt><ddclass="dd-description"> This option defines at
<spanstyle="font-weight:bold"><spanstyle="font-family:monospace">allow_change_subj: true|false</span></span></dt><ddclass="dd-description"> Allow occupants to change the subject.
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">allow_private_messages: true|false</span></span></dt><ddclass="dd-description"> Occupants can send private messages to other occupants.
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">allow_private_messages_from_visitors: anyone|moderators|nobody</span></span></dt><ddclass="dd-description"> Visitors can send private messages to other occupants.
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">allow_query_users: true|false</span></span></dt><ddclass="dd-description"> Occupants can send IQ queries to other occupants.
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">allow_user_invites: false|true</span></span></dt><ddclass="dd-description"> Allow occupants to send invitations.
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">allow_visitor_nickchange: true|false</span></span></dt><ddclass="dd-description"> Allow visitors to
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">anonymous: true|false</span></span></dt><ddclass="dd-description"> The room is anonymous:
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">logging: false|true</span></span></dt><ddclass="dd-description"> The public messages are logged using <spanstyle="font-family:monospace">mod_muc_log</span>.
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">max_users: 200</span></span></dt><ddclass="dd-description"> Maximum number of occupants in the room.
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">members_by_default: true|false</span></span></dt><ddclass="dd-description"> The occupants that enter the room are participants by default, so they have ’voice’.
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">members_only: false|true</span></span></dt><ddclass="dd-description"> Only members of the room can enter.
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">moderated: true|false</span></span></dt><ddclass="dd-description"> Only occupants with ’voice’ can send public messages.
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">password: "roompass123"</span></span></dt><ddclass="dd-description"> Password of the room. You may want to enable the next option too.
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">password_protected: false|true</span></span></dt><ddclass="dd-description"> The password is required to enter the room.
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">persistent: false|true</span></span></dt><ddclass="dd-description"> The room persists even if the last participant leaves.
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">public: true|false</span></span></dt><ddclass="dd-description"> The room is public in the list of the MUC service, so it can be discovered.
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">public_list: true|false</span></span></dt><ddclass="dd-description"> The list of participants is public, without requiring to enter the room.
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">title: "Room Title"</span></span></dt><ddclass="dd-description"> A human-readable title of the room.
</dd></dl>
All of those room options can be set to <spanstyle="font-family:monospace">true</span> or <spanstyle="font-family:monospace">false</span>,
except <spanstyle="font-family:monospace">password</span> and <spanstyle="font-family:monospace">title</span> which are strings,
and <spanstyle="font-family:monospace">max_users</span> that is integer.
<h3id="sec71"class="subsection">3.3.11  <ahref="#modmuclog"><spanstyle="font-family:monospace">mod_muc_log</span></a></h3><!--SEC END --><p><aid="modmuclog"></a>
</p><p>This module enables optional logging of Multi-User Chat (MUC) public conversations to
<h3id="sec72"class="subsection">3.3.12  <ahref="#modoffline"><spanstyle="font-family:monospace">mod_offline</span></a></h3><!--SEC END --><p><aid="modoffline"></a>
<h3id="sec73"class="subsection">3.3.13  <ahref="#modping"><spanstyle="font-family:monospace">mod_ping</span></a></h3><!--SEC END --><p><aid="modping"></a>
</p><p>This module implements support for XMPP Ping (<ahref="http://xmpp.org/extensions/xep-0199.html">XEP-0199</a>) and periodic keepalives.
<h3id="sec74"class="subsection">3.3.14  <ahref="#modprescounter"><spanstyle="font-family:monospace">mod_pres_counter</span></a></h3><!--SEC END --><p><aid="modprescounter"></a>
</p><p>This module detects flood/spam in presence subscription stanza traffic.
<h3id="sec75"class="subsection">3.3.15  <ahref="#modprivacy"><spanstyle="font-family:monospace">mod_privacy</span></a></h3><!--SEC END --><p><aid="modprivacy"></a>
</p><p>This module implements Blocking Communication (also known as Privacy Rules)
<spanstyle="font-weight:bold"><spanstyle="font-family:monospace">iqdisc: Discipline</span></span></dt><ddclass="dd-description"> This specifies
the processing discipline for Blocking Communication (<spanstyle="font-family:monospace">jabber:iq:privacy</span>) IQ queries (see section <ahref="#modiqdiscoption">3.3.2</a>).
<h3id="sec76"class="subsection">3.3.16  <ahref="#modprivate"><spanstyle="font-family:monospace">mod_private</span></a></h3><!--SEC END --><p><aid="modprivate"></a>
</p><p>This module adds support for Private XML Storage (<ahref="http://xmpp.org/extensions/xep-0049.html">XEP-0049</a>):
<spanstyle="font-weight:bold"><spanstyle="font-family:monospace">iqdisc: Discipline</span></span></dt><ddclass="dd-description"> This specifies
the processing discipline for Private XML Storage (<spanstyle="font-family:monospace">jabber:iq:private</span>) IQ queries (see section <ahref="#modiqdiscoption">3.3.2</a>).
<h3id="sec77"class="subsection">3.3.17  <ahref="#modproxy"><spanstyle="font-family:monospace">mod_proxy65</span></a></h3><!--SEC END --><p><aid="modproxy"></a>
<spanstyle="font-weight:bold"><spanstyle="font-family:monospace">host: HostName</span></span></dt><ddclass="dd-description"> This option defines the Jabber ID of the
service. If the <spanstyle="font-family:monospace">host</span> option is not specified, the Jabber ID will be the
hostname of the virtual host with the prefix ‘<spanstyle="font-family:monospace">proxy.</span>’. The keyword "@HOST@"
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">name: Text</span></span></dt><ddclass="dd-description">Defines Service Discovery name of the service.
Default is <spanstyle="font-family:monospace">"SOCKS5 Bytestreams"</span>.
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">ip: IP</span></span></dt><ddclass="dd-description">This option specifies which network interface
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">port: Number</span></span></dt><ddclass="dd-description">This option defines port to listen for
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">hostname: HostName</span></span></dt><ddclass="dd-description">Defines a hostname advertised
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">access: AccessName</span></span></dt><ddclass="dd-description">Defines ACL for file transfer initiators.
Default is <spanstyle="font-family:monospace">all</span>.
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">max_connections: Number</span></span></dt><ddclass="dd-description">Maximum number of
<h3id="sec78"class="subsection">3.3.18  <ahref="#modpubsub"><spanstyle="font-family:monospace">mod_pubsub</span></a></h3><!--SEC END --><p><aid="modpubsub"></a>
</p><p>This module offers a Publish-Subscribe Service (<ahref="http://xmpp.org/extensions/xep-0060.html">XEP-0060</a>).
The functionality in <spanstyle="font-family:monospace">mod_pubsub</span> can be extended using plugins.
The plugin that implements PEP (Personal Eventing via Pubsub) (<ahref="http://xmpp.org/extensions/xep-0163.html">XEP-0163</a>)
<spanstyle="font-weight:bold"><spanstyle="font-family:monospace">host: HostName</span></span></dt><ddclass="dd-description"> This option defines the Jabber ID of the
service. If the <spanstyle="font-family:monospace">host</span> option is not specified, the Jabber ID will be the
hostname of the virtual host with the prefix ‘<spanstyle="font-family:monospace">pubsub.</span>’. The keyword "@HOST@"
add <spanstyle="font-family:monospace">type=’plugin-name’</span> attribute to the <spanstyle="font-family:monospace">create</span> stanza element.
it will not work if you used the default "tree" nodetree before.</p><p>The "dag" nodetree provides experimental support for PubSub Collection Nodes (<ahref="http://xmpp.org/extensions/xep-0248.html">XEP-0248</a>).
<h3id="sec79"class="subsection">3.3.19  <ahref="#modregister"><spanstyle="font-family:monospace">mod_register</span></a></h3><!--SEC END --><p><aid="modregister"></a>
</p><p>This module adds support for In-Band Registration (<ahref="http://xmpp.org/extensions/xep-0077.html">XEP-0077</a>). This protocol
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">access_from: AccessName</span></span></dt><ddclass="dd-description"> By default, <spanstyle="font-family:monospace">ejabberd</span>
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">registration_watchers: [ JID, ...]</span></span></dt><ddclass="dd-description"> This option defines a
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">iqdisc: Discipline</span></span></dt><ddclass="dd-description"> This specifies
the processing discipline for In-Band Registration (<spanstyle="font-family:monospace">jabber:iq:register</span>) IQ queries (see section <ahref="#modiqdiscoption">3.3.2</a>).
</dd></dl><p>This module reads also another option defined globally for the server:
<h3id="sec80"class="subsection">3.3.20  <ahref="#modregisterweb"><spanstyle="font-family:monospace">mod_register_web</span></a></h3><!--SEC END --><p><aid="modregisterweb"></a>
</p><p>This module provides a web page where people can:
<spanstyle="font-weight:bold"><spanstyle="font-family:monospace">registration_watchers: [ JID, ...]</span></span></dt><ddclass="dd-description"> This option defines a
<h3id="sec81"class="subsection">3.3.21  <ahref="#modroster"><spanstyle="font-family:monospace">mod_roster</span></a></h3><!--SEC END --><p><aid="modroster"></a>
</p><p>This module implements roster management as defined in
<spanstyle="font-weight:bold"><spanstyle="font-family:monospace">iqdisc: Discipline</span></span></dt><ddclass="dd-description"> This specifies
the processing discipline for Roster Management (<spanstyle="font-family:monospace">jabber:iq:roster</span>) IQ queries (see section <ahref="#modiqdiscoption">3.3.2</a>).
<h3id="sec82"class="subsection">3.3.22  <ahref="#modservicelog"><spanstyle="font-family:monospace">mod_service_log</span></a></h3><!--SEC END --><p><aid="modservicelog"></a>
</p><p>This module adds support for logging end user packets via a XMPP message
<spanstyle="font-weight:bold"><spanstyle="font-family:monospace">loggers: [Names, ...]</span></span></dt><ddclass="dd-description"> With this option a (list of) service(s)
<h3id="sec83"class="subsection">3.3.23  <ahref="#modsharedroster"><spanstyle="font-family:monospace">mod_shared_roster</span></a></h3><!--SEC END --><p><aid="modsharedroster"></a>
</p><p>This module enables you to create shared roster groups. This means that you can
<spanstyle="font-weight:bold">Name</span></dt><ddclass="dd-description"> The name of the group, which will be displayed in the roster.
</dd><dtclass="dt-description"><spanstyle="font-weight:bold">Description</span></dt><ddclass="dd-description"> The description of the group. This parameter does not affect
</dd><dtclass="dt-description"><spanstyle="font-weight:bold">Members</span></dt><ddclass="dd-description"> A list of JIDs of group members, entered one per line in
<tr><tdstyle="text-align:left;border:solid 1px;white-space:nowrap">Description</td><tdstyle="text-align:left;border:solid 1px;white-space:nowrap">Members from the computer club</td></tr>
<tableborder=1style="border-spacing:0;"class="cellpadding1"><tr><tdstyle="text-align:left;border:solid 1px;white-space:nowrap">Identification</td><tdstyle="text-align:left;border:solid 1px;white-space:nowrap"> Group ‘<spanstyle="font-family:monospace">management</span>’</td><tdstyle="text-align:left;border:solid 1px;white-space:nowrap"> Group ‘<spanstyle="font-family:monospace">marketing</span>’</td><tdstyle="text-align:left;border:solid 1px;white-space:nowrap"> Group ‘<spanstyle="font-family:monospace">sales</span>’</td></tr>
<h3id="sec84"class="subsection">3.3.24  <ahref="#modsharedrosterldap"><spanstyle="font-family:monospace">mod_shared_roster_ldap</span></a></h3><!--SEC END --><p><aid="modsharedrosterldap"></a>
<h4id="sec85"class="subsubsection"><ahref="#msrlconfigparams">Configuration parameters</a></h4><!--SEC END --><p><aid="msrlconfigparams"></a></p><p>The module accepts the following configuration parameters. Some of them, if
in multiple places.</p><p><aid="msrlfilters"></a></p>
<!--TOC paragraph id="sec86" Filters-->
<h5id="sec86"class="paragraph"><ahref="#msrlfilters">Filters</a></h5><!--SEC END --><p><aid="msrlfilters"></a></p><p>These parameters specify LDAP filters used to query for shared roster information.
All of them are run against the <code>ldap_base</code>.</p><dlclass="description"><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">ldap_rfilter</span></span></dt><ddclass="dd-description">
You <em>must</em> specify it in some place in the configuration, there is no default.</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">ldap_ufilter</span></span></dt><ddclass="dd-description">
other parameters as follows (<code>[ldap_SOMETHING]</code> is used to mean “the
value of the configuration parameter <spanstyle="font-family:monospace">ldap_SOMETHING</span>”):<preclass="verbatim">(&(&([ldap_memberattr]=[ldap_memberattr_format])([ldap_groupattr]=%g))[ldap_filter])
</pre><p>Subsequently <spanstyle="font-family:monospace">%u</span> and <spanstyle="font-family:monospace">%g</span> are replaced with a <spanstyle="font-family:monospace">*</span>. This means
same way as <spanstyle="font-family:monospace">User Filter</span>.</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">ldap_filter</span></span></dt><ddclass="dd-description">
Additional filter which is AND-ed together with <spanstyle="font-family:monospace">User Filter</span> and <spanstyle="font-family:monospace">Group Filter</span>.
</dd></dl><p>Note that you will probably need to manually define the <spanstyle="font-family:monospace">User</span> and <spanstyle="font-family:monospace">Group Filter</span>s (since the auto-assembled ones will not work) if:
</p><ulclass="itemize"><liclass="li-itemize">
your <spanstyle="font-family:monospace">ldap_memberattr_format</span> is anything other than a simple <spanstyle="font-family:monospace">%u</span>,
</li><liclass="li-itemize"><spanstyle="font-weight:bold">and</span> the attribute specified with <spanstyle="font-family:monospace">ldap_memberattr</span> does not support substring matches.
</li></ul><p>
An example where it is the case is OpenLDAP and <spanstyle="font-family:monospace">(unique)MemberName</span> attribute from the <spanstyle="font-family:monospace">groupOf(Unique)Names</span> objectClass.
A symptom of this problem is that you will see messages such as the following in your <spanstyle="font-family:monospace">slapd.log</span>:
<h4id="sec87"class="subsubsection"><ahref="#msrlattrs">Attributes</a></h4><!--SEC END --><p><aid="msrlattrs"></a></p><p>These parameters specify the names of the attributes which hold interesting data
Defaults to <spanstyle="font-family:monospace">cn</span>.</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">ldap_groupdesc</span></span></dt><ddclass="dd-description">
Defaults to whatever <spanstyle="font-family:monospace">ldap_groupattr</span> is set.</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">ldap_memberattr</span></span></dt><ddclass="dd-description">
Defaults to <spanstyle="font-family:monospace">memberUid</span>.<p>The name of the attribute differs depending on the <spanstyle="font-family:monospace">objectClass</span> you use
Defaults to <spanstyle="font-family:monospace">cn</span>.</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">ldap_useruid</span></span></dt><ddclass="dd-description">
Defaults to <spanstyle="font-family:monospace">cn</span>.
</dd></dl><p><aid="msrlcontrolparams"></a></p>
<!--TOC subsubsection id="sec88" Control parameters-->
<h4id="sec88"class="subsubsection"><ahref="#msrlcontrolparams">Control parameters</a></h4><!--SEC END --><p><aid="msrlcontrolparams"></a></p><p>These paramters control the behaviour of the module.</p><dlclass="description"><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">ldap_memberattr_format</span></span></dt><ddclass="dd-description">
and Group Filters manually — see section <ahref="#msrlfilters">3.3.24</a>.</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">ldap_memberattr_format_re</span></span></dt><ddclass="dd-description">
<code>ldap_memberattr</code>.<p>An example value <spanstyle="font-family:monospace">"CN=(</span>\\<spanstyle="font-family:monospace">w*),(OU=.*,)*DC=company,DC=com"</span> works for user IDs such as the following:
</li><liclass="li-itemize">or the <spanstyle="font-family:monospace">re</span> module in unavailable in the current Erlang environment,
</li><liclass="li-itemize">or the regular expression does not compile,
</li></ul><p>
then instead of a regular expression, a simple format specified by <spanstyle="font-family:monospace">ldap_memberattr_format</span> is used. Also, in the last two cases an error
message is logged during the module initialization.</p><p>Also, note that in all cases <spanstyle="font-family:monospace">ldap_memberattr_format</span> (and <em>not</em> the
see section <ahref="#msrlfilters">3.3.24</a>.</p></dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">ldap_auth_check</span></span></dt><ddclass="dd-description">
Defaults to <spanstyle="font-family:monospace">on</span>.</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">ldap_user_cache_validity</span></span></dt><ddclass="dd-description">
fresh after retrieval. 300 by default. See section <ahref="#msrlconfigroster">3.3.24</a> on
how it is used during roster retrieval.</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">ldap_group_cache_validity</span></span></dt><ddclass="dd-description">
<h4id="sec89"class="subsubsection"><ahref="#msrlconnparams">Connection parameters</a></h4><!--SEC END --><p><aid="msrlconnparams"></a></p><p>The module also accepts the connection parameters, all of which default to the
top-level parameter of the same name, if unspecified. See <ahref="#ldapconnection">3.2.2</a>
for more information about them.</p><p><aid="msrlconfigroster"></a></p>
<!--TOC subsubsection id="sec90" Retrieving the roster-->
<h4id="sec90"class="subsubsection"><ahref="#msrlconfigroster">Retrieving the roster</a></h4><!--SEC END --><p><aid="msrlconfigroster"></a></p><p>When the module is called to retrieve the shared roster for a user, the
following algorithm is used:</p><olclass="enumerate"type=1><liclass="li-enumerate">
<aid="step:rfilter"></a> A list of names of groups to display is created: the <spanstyle="font-family:monospace">Roster Filter</span>
<spanstyle="font-family:monospace">ldap_groupattr</span>.</li><liclass="li-enumerate">Unless the group cache is fresh (see the <spanstyle="font-family:monospace">ldap_group_cache_validity</span> option), it is refreshed:<olclass="enumerate"type=a><liclass="li-enumerate">
Information for all groups is retrieved using a single query: the <spanstyle="font-family:monospace">Group Filter</span> is run against the Base DN, retrieving the values of attributes
named by <spanstyle="font-family:monospace">ldap_groupattr</span> (group ID), <spanstyle="font-family:monospace">ldap_groupdesc</span> (group
“Display Name”) and <spanstyle="font-family:monospace">ldap_memberattr</span> (IDs of group members).</li><liclass="li-enumerate">group “Display Name”, read from the attribute named by <spanstyle="font-family:monospace">ldap_groupdesc</span>, is stored in the cache for the given group</li><liclass="li-enumerate">the following processing takes place for each retrieved value of
attribute named by <spanstyle="font-family:monospace">ldap_memberattr</span>:
the user ID part of it is extracted using <spanstyle="font-family:monospace">ldap_memberattr_format(_re)</span>,</li><liclass="li-enumerate">then (unless <spanstyle="font-family:monospace">ldap_auth_check</span> is set to <spanstyle="font-family:monospace">off</span>) for each
found user ID, the module checks (using the <spanstyle="font-family:monospace">ejabberd</span> authentication
</li></ol></li><liclass="li-enumerate">For each item (group name) in the list of groups retrieved in step <ahref="#step%3Arfilter">1</a>:<olclass="enumerate"type=a><liclass="li-enumerate">
first, unless the user name cache is fresh (see the <spanstyle="font-family:monospace">ldap_user_cache_validity</span> option), it is refreshed by running the
<spanstyle="font-family:monospace">User Filter</span>, against the Base DN, retrieving the values of
attributes named by <spanstyle="font-family:monospace">ldap_useruid</span> and <spanstyle="font-family:monospace">ldap_userdesc</span>.
</li><liclass="li-enumerate">then, the display name for the given user ID is retrieved from the
<h4id="sec91"class="subsubsection"><ahref="#msrlconfigexample">Configuration examples</a></h4><!--SEC END --><p><aid="msrlconfigexample"></a></p><p>Since there are many possible
by looking at an example for a given DIT (or one resembling it).</p><p><aid="msrlconfigexampleflat"></a></p>
<!--TOC paragraph id="sec92" Flat DIT-->
<h5id="sec92"class="paragraph"><ahref="#msrlconfigexampleflat">Flat DIT</a></h5><!--SEC END --><p><aid="msrlconfigexampleflat"></a></p><p>This seems to be the kind of DIT for which this module was initially designed.
figure <ahref="#fig%3Amsrl-dit-flat">3.1</a>, the group of each user is stored in its <spanstyle="font-family:monospace">ou</span> attribute.</p><blockquoteclass="figure"><divclass="center"><divclass="center"><hrstyle="width:80%;height:2"></div>
<divclass="caption"><tablestyle="border-spacing:6px;border-collapse:separate;"class="cellpading0"><tr><tdstyle="vertical-align:top;text-align:left;">Figure 3.1: Flat DIT graph</td></tr>
</table></div>
<aid="fig:msrl-dit-flat"></a>
<divclass="center"><hrstyle="width:80%;height:2"></div></div></blockquote><p>Such layout has a few downsides, including:
</pre><p>…to be provided with a roster as shown in figure <ahref="#fig%3Amsrl-roster-flat">3.2</a> upon connecting as user <spanstyle="font-family:monospace">czesio</span>.</p><blockquoteclass="figure"><divclass="center"><divclass="center"><hrstyle="width:80%;height:2"></div>
<h5id="sec93"class="paragraph"><ahref="#msrlconfigexampledeep">Deep DIT</a></h5><!--SEC END --><p><aid="msrlconfigexampledeep"></a></p><p>This type of DIT contains distinctly typed objects for users and groups – see figure <ahref="#fig%3Amsrl-dit-deep">3.3</a>.
They are shown separated into different subtrees, but it’s not a requirement.</p><blockquoteclass="figure"><divclass="center"><divclass="center"><hrstyle="width:80%;height:2"></div>
<divclass="caption"><tablestyle="border-spacing:6px;border-collapse:separate;"class="cellpading0"><tr><tdstyle="vertical-align:top;text-align:left;">Figure 3.3: Example “deep” DIT graph</td></tr>
</table></div>
<aid="fig:msrl-dit-deep"></a>
<divclass="center"><hrstyle="width:80%;height:2"></div></div></blockquote><p>If you use the following example module configuration with it:
</pre><p>…and connect as user <spanstyle="font-family:monospace">czesio</span>, then <spanstyle="font-family:monospace">ejabberd</span> will provide you with
the roster shown in figure <ahref="#fig%3Amsrl-roster-deep">3.4</a>.</p><blockquoteclass="figure"><divclass="center"><divclass="center"><hrstyle="width:80%;height:2"></div>
<divclass="caption"><tablestyle="border-spacing:6px;border-collapse:separate;"class="cellpading0"><tr><tdstyle="vertical-align:top;text-align:left;">Figure 3.4: Example roster from “deep” DIT</td></tr>
<h3id="sec94"class="subsection">3.3.25  <ahref="#modsic"><spanstyle="font-family:monospace">mod_sic</span></a></h3><!--SEC END --><p><aid="modsic"></a>
</p><p>This module adds support for Server IP Check (<ahref="http://xmpp.org/extensions/xep-0279.html">XEP-0279</a>). This protocol
enables a client to discover its external IP address.</p><p>Options:
<spanstyle="font-weight:bold"><spanstyle="font-family:monospace">iqdisc: Discipline</span></span></dt><ddclass="dd-description"> This specifies
the processing discipline for <spanstyle="font-family:monospace">urn:xmpp:sic:0</span> IQ queries (see section <ahref="#modiqdiscoption">3.3.2</a>).
<h3id="sec95"class="subsection">3.3.26  <ahref="#modsip"><spanstyle="font-family:monospace">mod_sip</span></a></h3><!--SEC END --><p><aid="modsip"></a>
this option for every <spanstyle="font-family:monospace">Type</span> you can specify <spanstyle="font-family:monospace">Host</span> and <spanstyle="font-family:monospace">Port</span>
to set in <spanstyle="font-family:monospace">Via</span> header of outgoing SIP messages, where <spanstyle="font-family:monospace">Type</span> can be
<spanstyle="font-family:monospace">udp</span>, <spanstyle="font-family:monospace">tcp</span> or <spanstyle="font-family:monospace">tls</span>. <spanstyle="font-family:monospace">Host</span> is a string and <spanstyle="font-family:monospace">Port</span> is
a non negative integer. This is useful if you’re running your server in a non-standard
<h3id="sec96"class="subsection">3.3.27  <ahref="#modstats"><spanstyle="font-family:monospace">mod_stats</span></a></h3><!--SEC END --><p><aid="modstats"></a>
</p><p>This module adds support for Statistics Gathering (<ahref="http://xmpp.org/extensions/xep-0039.html">XEP-0039</a>). This protocol
allows you to retrieve next statistics from your <spanstyle="font-family:monospace">ejabberd</span> deployment:
<spanstyle="font-weight:bold"><spanstyle="font-family:monospace">iqdisc: Discipline</span></span></dt><ddclass="dd-description"> This specifies
the processing discipline for Statistics Gathering (<spanstyle="font-family:monospace">http://jabber.org/protocol/stats</span>) IQ queries (see section <ahref="#modiqdiscoption">3.3.2</a>).
</dd></dl><p>As there are only a small amount of clients (for example
<ahref="http://tkabber.jabber.ru/">Tkabber</a>) and software libraries with
<h3id="sec97"class="subsection">3.3.28  <ahref="#modtime"><spanstyle="font-family:monospace">mod_time</span></a></h3><!--SEC END --><p><aid="modtime"></a>
</p><p>This module features support for Entity Time (<ahref="http://xmpp.org/extensions/xep-0202.html">XEP-0202</a>). By using this XEP,
you are able to discover the time at another entity’s location.</p><p>Options:
<spanstyle="font-weight:bold"><spanstyle="font-family:monospace">iqdisc: Discipline</span></span></dt><ddclass="dd-description"> This specifies
the processing discipline for Entity Time (<spanstyle="font-family:monospace">jabber:iq:time</span>) IQ queries (see section <ahref="#modiqdiscoption">3.3.2</a>).
<h3id="sec98"class="subsection">3.3.29  <ahref="#modvcard"><spanstyle="font-family:monospace">mod_vcard</span></a></h3><!--SEC END --><p><aid="modvcard"></a>
</p><p>This module allows end users to store and retrieve their vCard, and to retrieve
other users vCards, as defined in vcard-temp (<ahref="http://xmpp.org/extensions/xep-0054.html">XEP-0054</a>). The module also
<spanstyle="font-weight:bold"><spanstyle="font-family:monospace">host: HostName</span></span></dt><ddclass="dd-description"> This option defines the Jabber ID of the
service. If the <spanstyle="font-family:monospace">host</span> option is not specified, the Jabber ID will be the
hostname of the virtual host with the prefix ‘<spanstyle="font-family:monospace">vjud.</span>’. The keyword "@HOST@"
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">iqdisc: Discipline</span></span></dt><ddclass="dd-description"> This specifies
the processing discipline for <spanstyle="font-family:monospace">vcard-temp</span> IQ queries (see section <ahref="#modiqdiscoption">3.3.2</a>).
list. The default value is <spanstyle="font-family:monospace">true</span>.
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">matches: infinity|Number</span></span></dt><ddclass="dd-description">With this option, the number of reported
search results can be limited. If the option’s value is set to <spanstyle="font-family:monospace">infinity</span>,
all search results are reported. The default value is <spanstyle="font-family:monospace">30</span>.
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">search_all_hosts, true|false</span></span></dt><ddclass="dd-description">If this option is set
to <spanstyle="font-family:monospace">true</span>, search operations will apply to all virtual hosts. Otherwise
only the current host will be searched. The default value is <spanstyle="font-family:monospace">true</span>.
This option is available in <spanstyle="font-family:monospace">mod_vcard</span>when using Mnesia, but not when using ODBC storage.
<h3id="sec99"class="subsection">3.3.30  <ahref="#modvcardldap"><spanstyle="font-family:monospace">mod_vcard_ldap</span></a></h3><!--SEC END --><p><aid="modvcardldap"></a>
</p><p><spanstyle="font-family:monospace">ejabberd</span> can map LDAP attributes to vCard fields. This behaviour is
implemented in the <spanstyle="font-family:monospace">mod_vcard_ldap</span> module. This module does not depend on the
authentication method (see <ahref="#ldapauth">3.2.2</a>).</p><p>Usually <spanstyle="font-family:monospace">ejabberd</span> treats LDAP as a read-only storage:
<spanstyle="font-family:monospace">ldap_deref_aliases</span> and <spanstyle="font-family:monospace">ldap_filter</span>.
See section <ahref="#ldapauth">3.2.2</a> for detailed information
about these options. If one of these options is not set, <spanstyle="font-family:monospace">ejabberd</span> will look
for the top-level option with the same name.</p><p>The second group of parameters
consists of the following <spanstyle="font-family:monospace">mod_vcard_ldap</span>-specific options:</p><dlclass="description"><dtclass="dt-description">
<spanstyle="font-weight:bold"><spanstyle="font-family:monospace">host: HostName</span></span></dt><ddclass="dd-description"> This option defines the Jabber ID of the
service. If the <spanstyle="font-family:monospace">host</span> option is not specified, the Jabber ID will be the
hostname of the virtual host with the prefix ‘<spanstyle="font-family:monospace">vjud.</span>’. The keyword "@HOST@"
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">iqdisc: Discipline</span></span></dt><ddclass="dd-description"> This specifies
the processing discipline for <spanstyle="font-family:monospace">vcard-temp</span> IQ queries (see section <ahref="#modiqdiscoption">3.3.2</a>).
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">{search, true|false}</span></span></dt><ddclass="dd-description">This option specifies whether the search
functionality is enabled (value: <spanstyle="font-family:monospace">true</span>) or disabled (value:
<spanstyle="font-family:monospace">false</span>). If disabled, the option <spanstyle="font-family:monospace">host</span> will be ignored and the
list. The default value is <spanstyle="font-family:monospace">true</span>.
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">{matches, infinity|Number}</span></span></dt><ddclass="dd-description">With this option, the number of reported
search results can be limited. If the option’s value is set to <spanstyle="font-family:monospace">infinity</span>,
all search results are reported. The default value is <spanstyle="font-family:monospace">30</span>.
</pre><p>Now we want to use users LDAP-info as their vCards. We have four attributes
defined in our LDAP schema: <spanstyle="font-family:monospace">"mail"</span>— email address, <spanstyle="font-family:monospace">"givenName"</span>
— first name, <spanstyle="font-family:monospace">"sn"</span>— second name, <spanstyle="font-family:monospace">"birthDay"</span>— birthday.
Also we want users to search each other. Let’s see how we can set it up:</p><preclass="verbatim">{modules,
<h3id="sec100"class="subsection">3.3.31  <ahref="#modvcardxupdate"><spanstyle="font-family:monospace">mod_vcard_xupdate</span></a></h3><!--SEC END --><p><aid="modvcardxupdate"></a>
</p><p>The user’s client can store an avatar in the user vCard.
The vCard-Based Avatars protocol (<ahref="http://xmpp.org/extensions/xep-0153.html">XEP-0153</a>)
However, simple or small clients may not implement that protocol.</p><p>If this module is enabled, all the outgoing client presence stanzas get automatically
<h3id="sec101"class="subsection">3.3.32  <ahref="#modversion"><spanstyle="font-family:monospace">mod_version</span></a></h3><!--SEC END --><p><aid="modversion"></a>
</p><p>This module implements Software Version (<ahref="http://xmpp.org/extensions/xep-0092.html">XEP-0092</a>). Consequently, it
answers <spanstyle="font-family:monospace">ejabberd</span>’s version when queried.</p><p>Options:
<spanstyle="font-weight:bold"><spanstyle="font-family:monospace">show_os: true|false</span></span></dt><ddclass="dd-description">Should the operating system be revealed or not.
The default value is <spanstyle="font-family:monospace">true</span>.
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">iqdisc: Discipline</span></span></dt><ddclass="dd-description"> This specifies
the processing discipline for Software Version (<spanstyle="font-family:monospace">jabber:iq:version</span>) IQ queries (see section <ahref="#modiqdiscoption">3.3.2</a>).
</dd></dl><p><aid="manage"></a></p>
<!--TOC chapter id="sec102" Managing an <span style="font-family:monospace">ejabberd</span> Server-->
<h1id="sec102"class="chapter">Chapter 4  <ahref="#manage">Managing an <spanstyle="font-family:monospace">ejabberd</span> Server</a></h1><!--SEC END --><p><aid="manage"></a></p><p><aid="ejabberdctl"></a></p>
<h2id="sec103"class="section">4.1  <ahref="#ejabberdctl"><spanstyle="font-family:monospace">ejabberdctl</span></a></h2><!--SEC END --><p><aid="ejabberdctl"></a></p><p>With the <spanstyle="font-family:monospace">ejabberdctl</span> command line administration script
you can execute <spanstyle="font-family:monospace">ejabberdctl commands</span> (described in the next section, <ahref="#ectl-commands">4.1.1</a>)
and also many general <spanstyle="font-family:monospace">ejabberd commands</span> (described in section <ahref="#eja-commands">4.2</a>).
in a local or remote <spanstyle="font-family:monospace">ejabberd</span> server (by providing the argument <spanstyle="font-family:monospace">--node NODENAME</span>).</p><p>The <spanstyle="font-family:monospace">ejabberdctl</span> script can be configured in the file <spanstyle="font-family:monospace">ejabberdctl.cfg</span>.
This file includes detailed information about each configurable option. See section <ahref="#erlangconfiguration">4.1.2</a>.</p><p>The <spanstyle="font-family:monospace">ejabberdctl</span> script returns a numerical status code.
Success is represented by <spanstyle="font-family:monospace">0</span>,
error is represented by <spanstyle="font-family:monospace">1</span>,
for example using: <spanstyle="font-family:monospace">echo $?</span></p><p>If you use Bash, you can get Bash completion by copying the file <spanstyle="font-family:monospace">tools/ejabberdctl.bc</span>
to the directory <spanstyle="font-family:monospace">/etc/bash_completion.d/</span> (in Debian, Ubuntu, Fedora and maybe others).</p><p><aid="ectl-commands"></a></p>
<h3id="sec104"class="subsection">4.1.1  <ahref="#ectl-commands">ejabberdctl Commands</a></h3><!--SEC END --><p><aid="ectl-commands"></a></p><p>When <spanstyle="font-family:monospace">ejabberdctl</span> is executed without any parameter,
it displays the available options. If there isn’t an <spanstyle="font-family:monospace">ejabberd</span> server running,
<spanstyle="font-weight:bold"><spanstyle="font-family:monospace">start</span></span></dt><ddclass="dd-description"> Start <spanstyle="font-family:monospace">ejabberd</span> in background mode. This is the default method.
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">debug</span></span></dt><ddclass="dd-description"> Attach an Erlang shell to an already existing <spanstyle="font-family:monospace">ejabberd</span> server. This allows to execute commands interactively in the <spanstyle="font-family:monospace">ejabberd</span> server.
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">live</span></span></dt><ddclass="dd-description"> Start <spanstyle="font-family:monospace">ejabberd</span> in live mode: the shell keeps attached to the started server, showing log messages and allowing to execute interactive commands.
</dd></dl><p>If there is an <spanstyle="font-family:monospace">ejabberd</span> server running in the system,
<spanstyle="font-family:monospace">ejabberdctl</span> shows the <spanstyle="font-family:monospace">ejabberdctl commands</span> described bellow
and all the <spanstyle="font-family:monospace">ejabberd commands</span> available in that server (see <ahref="#list-eja-commands">4.2.1</a>).</p><p>The <spanstyle="font-family:monospace">ejabberdctl commands</span> are:
<spanstyle="font-weight:bold"><spanstyle="font-family:monospace">help</span></span></dt><ddclass="dd-description"> Get help about ejabberdctl or any available command. Try <spanstyle="font-family:monospace">ejabberdctl help help</span>.
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">status</span></span></dt><ddclass="dd-description"> Check the status of the <spanstyle="font-family:monospace">ejabberd</span> server.
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">stop</span></span></dt><ddclass="dd-description"> Stop the <spanstyle="font-family:monospace">ejabberd</span> server.
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">restart</span></span></dt><ddclass="dd-description"> Restart the <spanstyle="font-family:monospace">ejabberd</span> server.
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">mnesia</span></span></dt><ddclass="dd-description"> Get information about the Mnesia database.
</dd></dl><p>The <spanstyle="font-family:monospace">ejabberdctl</span> script can be restricted to require authentication
and execute some <spanstyle="font-family:monospace">ejabberd commands</span>; see <ahref="#accesscommands">4.2.2</a>.
Add the option to the file <spanstyle="font-family:monospace">ejabberd.yml</span>.
</pre><p>If account <spanstyle="font-family:monospace">robot1@example.org</span> is registered in <spanstyle="font-family:monospace">ejabberd</span> with password <spanstyle="font-family:monospace">abcdef</span>
<h3id="sec105"class="subsection">4.1.2  <ahref="#erlangconfiguration">Erlang Runtime System</a></h3><!--SEC END --><p><aid="erlangconfiguration"></a></p><p><spanstyle="font-family:monospace">ejabberd</span> is an Erlang/OTP application that runs inside an Erlang runtime system.
If using <spanstyle="font-family:monospace">-sname</span>, specify either this option or <spanstyle="font-family:monospace">-kernel inetrc filepath</span>.
Tell Erlang runtime system to start the <spanstyle="font-family:monospace">ejabberd</span> application.
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">-mnesia dir ’"/var/lib/ejabberd/"’</span></span></dt><ddclass="dd-description">
<h2id="sec106"class="section">4.2  <ahref="#eja-commands"><spanstyle="font-family:monospace">ejabberd</span> Commands</a></h2><!--SEC END --><p><aid="eja-commands"></a></p><p>An <spanstyle="font-family:monospace">ejabberd command</span> is an abstract function identified by a name,
that is registered in the <spanstyle="font-family:monospace">ejabberd_commands</span> service.
Those commands can be defined in any Erlang module and executed using any valid frontend.</p><p><spanstyle="font-family:monospace">ejabberd</span> includes two frontends to execute <spanstyle="font-family:monospace">ejabberd commands</span>: the script <spanstyle="font-family:monospace">ejabberdctl</span> (<ahref="#ejabberdctl">4.1</a>)
and the <spanstyle="font-family:monospace">ejabberd_xmlrpc</span> listener (<ahref="#listened-module">3.1.4</a>).
<!--TOC subsection id="sec107" List of ejabberd Commands-->
<h3id="sec107"class="subsection">4.2.1  <ahref="#list-eja-commands">List of ejabberd Commands</a></h3><!--SEC END --><p><aid="list-eja-commands"></a></p><p><spanstyle="font-family:monospace">ejabberd</span> includes a few ejabberd Commands by default.
When more modules are installed, new commands may be available in the frontends.</p><p>The easiest way to get a list of the available commands, and get help for them is to use
<spanstyle="font-weight:bold"><spanstyle="font-family:monospace">reopen_log</span></span></dt><ddclass="dd-description"> Reopen the log files after they were renamed.
memory and processor. In that case it’s preferable to use <spanstyle="font-family:monospace">backup</span> and <spanstyle="font-family:monospace">install_fallback</span>.
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">delete_expired_messages</span></span></dt><ddclass="dd-description"> This option can be used to delete old messages
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">delete_old_messages days</span></span></dt><ddclass="dd-description"> Delete offline messages older than the given days.
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">register user host password</span></span></dt><ddclass="dd-description"> Register an account in that domain with the given password.
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">unregister user host</span></span></dt><ddclass="dd-description"> Unregister the given account.
</dd></dl><p><aid="accesscommands"></a></p>
<!--TOC subsection id="sec108" Restrict Execution with AccessCommands-->
<h3id="sec108"class="subsection">4.2.2  <ahref="#accesscommands">Restrict Execution with AccessCommands</a></h3><!--SEC END --><p><aid="accesscommands"></a></p><p>The frontends can be configured to restrict access to certain commands.
<h2id="sec109"class="section">4.3  <ahref="#webadmin">Web Admin</a></h2><!--SEC END --><p><aid="webadmin"></a>
</p><p>The <spanstyle="font-family:monospace">ejabberd</span> Web Admin allows to administer most of <spanstyle="font-family:monospace">ejabberd</span> using a web browser.</p><p>This feature is enabled by default:
a <spanstyle="font-family:monospace">ejabberd_http</span> listener with the option <spanstyle="font-family:monospace">web_admin</span> (see
section <ahref="#listened">3.1.4</a>) is included in the listening ports. Then you can open
<code>http://server:port/admin/</code> in your favourite web browser. You
will be asked to enter the username (the <em>full</em> Jabber ID) and password
of an <spanstyle="font-family:monospace">ejabberd</span> user with administrator rights. After authentication
you will see a page similar to figure <ahref="#fig%3Awebadmmain">4.1</a>.</p><blockquoteclass="figure"><divclass="center"><divclass="center"><hrstyle="width:80%;height:2"></div>
<divclass="caption"><tablestyle="border-spacing:6px;border-collapse:separate;"class="cellpading0"><tr><tdstyle="vertical-align:top;text-align:left;">Figure 4.1: Top page from the Web Admin</td></tr>
statistics,…</p><p>The access rule <spanstyle="font-family:monospace">configure</span> determines what accounts can access the Web Admin and modify it.
The access rule <spanstyle="font-family:monospace">webadmin_view</span> is to grant only view access: those accounts can browse the Web Admin with read-only access.</p><p>Example configurations:
the environment variable <spanstyle="font-family:monospace">EJABBERD_DOC_PATH</span>.
See section <ahref="#erlangconfiguration">4.1.2</a>.</p><p><aid="adhoccommands"></a></p>
<!--TOC section id="sec110" Ad-hoc Commands-->
<h2id="sec110"class="section">4.4  <ahref="#adhoccommands">Ad-hoc Commands</a></h2><!--SEC END --><p><aid="adhoccommands"></a></p><p>If you enable <spanstyle="font-family:monospace">mod_configure</span> and <spanstyle="font-family:monospace">mod_adhoc</span>,
you can perform several administrative tasks in <spanstyle="font-family:monospace">ejabberd</span>
<h2id="sec111"class="section">4.5  <ahref="#changeerlangnodename">Change Computer Hostname</a></h2><!--SEC END --><p><aid="changeerlangnodename"></a></p><p><spanstyle="font-family:monospace">ejabberd</span> uses the distributed Mnesia database.
if you change the name of the machine in which <spanstyle="font-family:monospace">ejabberd</span> runs,
or when you move <spanstyle="font-family:monospace">ejabberd</span> to a different machine.</p><p>You have two ways to use the old Mnesia database in an ejabberd with new node name:
put the old node name in <spanstyle="font-family:monospace">ejabberdctl.cfg</span>,
or convert the database to the new node name.</p><p>Those example steps will backup, convert and load the Mnesia database.
<h1id="sec112"class="chapter">Chapter 5  <ahref="#secure">Securing <spanstyle="font-family:monospace">ejabberd</span></a></h1><!--SEC END --><p><aid="secure"></a></p><p><aid="firewall"></a></p>
<!--TOC section id="sec113" Firewall Settings-->
<h2id="sec113"class="section">5.1  <ahref="#firewall">Firewall Settings</a></h2><!--SEC END --><p><aid="firewall"></a>
</p><p>You need to take the following TCP ports in mind when configuring your firewall:
<tr><tdstyle="text-align:left;border:solid 1px;white-space:nowrap">5222</td><tdstyle="text-align:left;border:solid 1px;white-space:nowrap">Standard port for Jabber/XMPP client connections, plain or STARTTLS.</td></tr>
<tr><tdstyle="text-align:left;border:solid 1px;white-space:nowrap">5223</td><tdstyle="text-align:left;border:solid 1px;white-space:nowrap">Standard port for Jabber client connections using the old SSL method.</td></tr>
<tr><tdstyle="text-align:left;border:solid 1px;white-space:nowrap">5269</td><tdstyle="text-align:left;border:solid 1px;white-space:nowrap">Standard port for Jabber/XMPP server connections.</td></tr>
<tr><tdstyle="text-align:left;border:solid 1px;white-space:nowrap">4369</td><tdstyle="text-align:left;border:solid 1px;white-space:nowrap">EPMD (section <ahref="#epmd">5.2</a>) listens for Erlang node name requests.</td></tr>
<tr><tdstyle="text-align:left;border:solid 1px;white-space:nowrap">port range</td><tdstyle="text-align:left;border:solid 1px;white-space:nowrap">Used for connections between Erlang nodes. This range is configurable (see section <ahref="#epmd">5.2</a>).</td></tr>
<h2id="sec114"class="section">5.2  <ahref="#epmd">epmd</a></h2><!--SEC END --><p><aid="epmd"></a></p><p><ahref="http://www.erlang.org/doc/man/epmd.html">epmd (Erlang Port Mapper Daemon)</a>
<spanstyle="font-family:monospace">ejabberd</span> needs <spanstyle="font-family:monospace">epmd</span> to use <spanstyle="font-family:monospace">ejabberdctl</span> and also when clustering <spanstyle="font-family:monospace">ejabberd</span> nodes.
If <spanstyle="font-family:monospace">ejabberd</span> is stopped, and there aren’t any other Erlang programs
running in the system, you can safely stop <spanstyle="font-family:monospace">epmd</span> if you want.</p><p><spanstyle="font-family:monospace">ejabberd</span> runs inside an Erlang node.
To communicate with <spanstyle="font-family:monospace">ejabberd</span>, the script <spanstyle="font-family:monospace">ejabberdctl</span> starts a new Erlang node
and connects to the Erlang node that holds <spanstyle="font-family:monospace">ejabberd</span>.
or configure the option <spanstyle="font-family:monospace">ERL_EPMD_ADDRESS</span> in the file <spanstyle="font-family:monospace">ejabberdctl.cfg</span>.</p><p>If you build a cluster of several <spanstyle="font-family:monospace">ejabberd</span> instances,
each <spanstyle="font-family:monospace">ejabberd</span> instance is called an <spanstyle="font-family:monospace">ejabberd</span> node.
Those <spanstyle="font-family:monospace">ejabberd</span> nodes use a special Erlang communication method to
Remember to block the port so Internet doesn’t have access to it.</p><p>Once an Erlang node solved the node name of another Erlang node using EPMD and port 4369,
<h2id="sec115"class="section">5.3  <ahref="#cookie">Erlang Cookie</a></h2><!--SEC END --><p><aid="cookie"></a></p><p>The Erlang cookie is a string with numbers and letters.
An Erlang node reads the cookie at startup from the command-line parameter <spanstyle="font-family:monospace">-setcookie</span>.
If not indicated, the cookie is read from the cookie file <spanstyle="font-family:monospace">$HOME/.erlang.cookie</span>.
The recommended way to secure the Erlang node is to block the port 4369.</p><p><aid="nodename"></a></p>
<!--TOC section id="sec116" Erlang Node Name-->
<h2id="sec116"class="section">5.4  <ahref="#nodename">Erlang Node Name</a></h2><!--SEC END --><p><aid="nodename"></a></p><p>An Erlang node may have a node name.
The name can be short (if indicated with the command-line parameter <spanstyle="font-family:monospace">-sname</span>)
or long (if indicated with the parameter <spanstyle="font-family:monospace">-name</span>).
Starting an Erlang node with -sname limits the communication between Erlang nodes to the LAN.</p><p>Using the option <spanstyle="font-family:monospace">-sname</span> instead of <spanstyle="font-family:monospace">-name</span> is a simple method
<h2id="sec117"class="section">5.5  <ahref="#secure-files">Securing Sensitive Files</a></h2><!--SEC END --><p><aid="secure-files"></a></p><p><spanstyle="font-family:monospace">ejabberd</span> stores sensitive data in the file system either in plain text or binary files.
so it is preferable to secure the whole <spanstyle="font-family:monospace">/etc/ejabberd/</span> directory.
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">ejabberd service log: /var/log/ejabberd/ejabberd.log</span></span></dt><ddclass="dd-description">
serving this connection, otherwise a new connection is opened.</p><p><aid="cluster"></a></p>
<!--TOC section id="sec124" Clustering Setup-->
<h2id="sec124"class="section">6.2  <ahref="#cluster">Clustering Setup</a></h2><!--SEC END --><p><aid="cluster"></a>
</p><p>Suppose you already configured <spanstyle="font-family:monospace">ejabberd</span> on one machine named (<spanstyle="font-family:monospace">first</span>),
and you need to setup another one to make an <spanstyle="font-family:monospace">ejabberd</span> cluster. Then do
following steps:</p><olclass="enumerate"type=1><liclass="li-enumerate">
Copy <code>~ejabberd/.erlang.cookie</code> file from <spanstyle="font-family:monospace">first</span> to
<spanstyle="font-family:monospace">second</span>.<p>(alt) You can also add ‘<code>-setcookie content_of_.erlang.cookie</code>’
option to all ‘<spanstyle="font-family:monospace">erl</span>’ commands below.</p></li><liclass="li-enumerate">On <spanstyle="font-family:monospace">second</span> run the following command as the <spanstyle="font-family:monospace">ejabberd</span> daemon user,
in the working directory of <spanstyle="font-family:monospace">ejabberd</span>:<preclass="verbatim">erl -sname ejabberd \
call <ahref="#ejabberdctl">4.1</a> without options and it will show some help,
including the Mnesia database spool dir.</p><preclass="verbatim">running db nodes = [ejabberd@first, ejabberd@second]
</pre></li><liclass="li-enumerate">Now run the following in the same ‘<spanstyle="font-family:monospace">erl</span>’ session:<preclass="verbatim">mnesia:change_table_copy_type(schema, node(), disc_copies).
</pre><p>This will create local disc storage for the database.</p><p>(alt) Change storage type of the <spanstyle="font-family:monospace">scheme</span> table to ‘RAM and disc
copy’ on the second node via the Web Admin.</p></li><liclass="li-enumerate">Now you can add replicas of various tables to this node with
‘<code>mnesia:add_table_copy</code>’ or
‘<code>mnesia:change_table_copy_type</code>’ as above (just replace
‘<code>schema</code>’ with another table name and ‘<code>disc_copies</code>’
can be replaced with ‘<code>ram_copies</code>’ or
‘<code>disc_only_copies</code>’).<p>Which tables to replicate is very dependant on your needs, you can get
some hints from the command ‘<code>mnesia:info().</code>’, by looking at the
size of tables and the default storage type for each table on ’first’.</p><p>Replicating a table makes lookups in this table faster on this node.
of the replicas is down, other replicas will be used.</p><p>Also <ahref="http://www.erlang.org/doc/apps/mnesia/Mnesia_chap5.html#5.3">section 5.3 (Table Fragmentation) of Mnesia User’s Guide</a> can be helpful.
</p><p>(alt) Same as in previous item, but for other tables.</p></li><liclass="li-enumerate">Run ‘<code>init:stop().</code>’ or just ‘<code>q().</code>’ to exit from
transfered and processed all data it needed from <spanstyle="font-family:monospace">first</span>.</li><liclass="li-enumerate">Now run <spanstyle="font-family:monospace">ejabberd</span> on <spanstyle="font-family:monospace">second</span> with a configuration similar as
on <spanstyle="font-family:monospace">first</span>: you probably do not need to duplicate ‘<code>acl</code>’
and ‘<code>access</code>’ options because they will be taken from
<spanstyle="font-family:monospace">first</span>; and <code>mod_irc</code> should be
<h3id="sec126"class="subsection">6.3.1  <ahref="#domainlb">Domain Load-Balancing Algorithm</a></h3><!--SEC END --><p><aid="domainlb"></a>
</p><p><spanstyle="font-family:monospace">ejabberd</span> includes an algorithm to load balance the components that are plugged on an <spanstyle="font-family:monospace">ejabberd</span> cluster. It means that you can plug one or several instances of the same component on each <spanstyle="font-family:monospace">ejabberd</span> cluster and that the traffic will be automatically distributed.</p><p>The default distribution algorithm try to deliver to a local instance of a component. If several local instances are available, one instance is chosen randomly. If no instance is available locally, one instance is chosen randomly among the remote component instances.</p><p>If you need a different behaviour, you can change the load balancing behaviour with the option <spanstyle="font-family:monospace">domain_balancing</span>. The syntax of the option is the following:
</p><dlclass="description"><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">domain_balancing: BalancingCriteria</span></span></dt></dl><p>Several balancing criteria are available:
</p><ulclass="itemize"><liclass="li-itemize">
<spanstyle="font-family:monospace">destination</span>: the full JID of the packet <spanstyle="font-family:monospace">to</span> attribute is used.
</li><liclass="li-itemize"><spanstyle="font-family:monospace">source</span>: the full JID of the packet <spanstyle="font-family:monospace">from</span> attribute is used.
</li><liclass="li-itemize"><spanstyle="font-family:monospace">bare_destination</span>: the bare JID (without resource) of the packet <spanstyle="font-family:monospace">to</span> attribute is used.
</li><liclass="li-itemize"><spanstyle="font-family:monospace">bare_source</span>: the bare JID (without resource) of the packet <spanstyle="font-family:monospace">from</span> attribute is used.
</li></ul><p>If the value corresponding to the criteria is the same, the same component instance in the cluster will be used.</p><p><aid="lbbuckets"></a></p>
<h3id="sec127"class="subsection">6.3.2  <ahref="#lbbuckets">Load-Balancing Buckets</a></h3><!--SEC END --><p><aid="lbbuckets"></a>
</p><p>When there is a risk of failure for a given component, domain balancing can cause service trouble. If one component is failing the service will not work correctly unless the sessions are rebalanced.</p><p>In this case, it is best to limit the problem to the sessions handled by the failing component. This is what the <spanstyle="font-family:monospace">domain_balancing_component_number</span> option does, making the load balancing algorithm not dynamic, but sticky on a fix number of component instances.</p><p>The syntax is:
<h1id="sec128"class="chapter">Chapter 7  <ahref="#debugging">Debugging</a></h1><!--SEC END --><p><aid="debugging"></a>
</p><p><aid="logfiles"></a></p>
<!--TOC section id="sec129" Log Files-->
<h2id="sec129"class="section">7.1  <ahref="#logfiles">Log Files</a></h2><!--SEC END --><p><aid="logfiles"></a></p><p>An <spanstyle="font-family:monospace">ejabberd</span> node writes two log files:
<spanstyle="font-weight:bold"><spanstyle="font-family:monospace">ejabberd.log</span></span></dt><ddclass="dd-description"> is the ejabberd service log, with the messages reported by <spanstyle="font-family:monospace">ejabberd</span> code
</dd><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">erlang.log</span></span></dt><ddclass="dd-description"> is the Erlang/OTP system log, with the messages reported by Erlang/OTP using SASL (System Architecture Support Libraries)
</dd></dl><p>The option <spanstyle="font-family:monospace">loglevel</span> modifies the verbosity of the file ejabberd.log. The syntax:
<spanstyle="font-weight:bold"><spanstyle="font-family:monospace">loglevel: Level</span></span></dt><ddclass="dd-description"> The standard form to set a global log level.
</dd></dl><p>The possible <spanstyle="font-family:monospace">Level</span> are:
<spanstyle="font-weight:bold"><spanstyle="font-family:monospace">0</span></span></dt><ddclass="dd-description"> No ejabberd log at all (not recommended)
and also renames the old ones if you didn’t rename them.</p><p><aid="debugconsole"></a></p>
<!--TOC section id="sec130" Debug Console-->
<h2id="sec130"class="section">7.2  <ahref="#debugconsole">Debug Console</a></h2><!--SEC END --><p><aid="debugconsole"></a></p><p>The Debug Console is an Erlang shell attached to an already running <spanstyle="font-family:monospace">ejabberd</span> server.
With this Erlang shell, an experienced administrator can perform complex tasks.</p><p>This shell gives complete control over the <spanstyle="font-family:monospace">ejabberd</span> server,
<ahref="http://www.ejabberd.im/interconnect-erl-nodes">Interconnecting Erlang Nodes</a></p><p>To exit the shell, close the window or press the keys: control+c control+c.</p><p><aid="watchdog"></a></p>
<!--TOC section id="sec131" Watchdog Alerts-->
<h2id="sec131"class="section">7.3  <ahref="#watchdog">Watchdog Alerts</a></h2><!--SEC END --><p><aid="watchdog"></a>
</p><p><spanstyle="font-family:monospace">ejabberd</span> includes a watchdog mechanism that may be useful to developers
in the <spanstyle="font-family:monospace">ejabberd</span> configuration file.</p><p>The syntax is:
</p><dlclass="description"><dtclass="dt-description"><spanstyle="font-weight:bold"><spanstyle="font-family:monospace">watchdog_admins: [JID, ...]</span></span></dt></dl><p>The memory consumed is measured in <spanstyle="font-family:monospace">words</span>:
<!--TOC chapter id="sec132" Internationalization and Localization-->
<h1id="sec132"class="chapter">Appendix A  <ahref="#i18ni10n">Internationalization and Localization</a></h1><!--SEC END --><p><aid="i18ni10n"></a>
</p><p>The source code of <spanstyle="font-family:monospace">ejabberd</span> supports localization.
using any capable program (KBabel, Lokalize, Poedit...) or a simple text editor.</p><p>Then gettext
is used to extract, update and export those .po files to the .msg format read by <spanstyle="font-family:monospace">ejabberd</span>.
To perform those management tasks, in the <spanstyle="font-family:monospace">src/</span> directory execute <spanstyle="font-family:monospace">make translations</span>.
The translatable strings are extracted from source code to generate the file <spanstyle="font-family:monospace">ejabberd.pot</span>.
Finally those .po files are exported to .msg files, that have a format easily readable by <spanstyle="font-family:monospace">ejabberd</span>.</p><p>All built-in modules support the <spanstyle="font-family:monospace">xml:lang</span> attribute inside IQ queries.
Figure <ahref="#fig%3Adiscorus">A.1</a>, for example, shows the reply to the following query:
<divclass="caption"><tablestyle="border-spacing:6px;border-collapse:separate;"class="cellpading0"><tr><tdstyle="vertical-align:top;text-align:left;">Figure A.1: Service Discovery when <spanstyle="font-family:monospace">xml:lang=’ru’</span></td></tr>
</table></div>
<aid="fig:discorus"></a>
<divclass="center"><hrstyle="width:80%;height:2"></div></div></blockquote><p>The Web Admin also supports the <code>Accept-Language</code> HTTP header.</p><blockquoteclass="figure"><divclass="center"><divclass="center"><hrstyle="width:80%;height:2"></div>
<divclass="caption"><tablestyle="border-spacing:6px;border-collapse:separate;"class="cellpading0"><tr><tdstyle="vertical-align:top;text-align:left;">Figure A.2: Web Admin showing a virtual host when the web browser provides the
<h1id="sec133"class="chapter">Appendix B  <ahref="#releasenotes">Release Notes</a></h1><!--SEC END --><p><aid="releasenotes"></a>
</p><p>Release notes are available from <ahref="http://www.process-one.net/en/ejabberd/release_notes/">ejabberd Home Page</a></p><p><aid="acknowledgements"></a></p>
<!--TOC chapter id="sec134" Acknowledgements-->
<h1id="sec134"class="chapter">Appendix C  <ahref="#acknowledgements">Acknowledgements</a></h1><!--SEC END --><p><aid="acknowledgements"></a></p><p>Thanks to all people who contributed to this guide:
<h1id="sec135"class="chapter">Appendix D  <ahref="#copyright">Copyright Information</a></h1><!--SEC END --><p><aid="copyright"></a></p><p>Ejabberd Installation and Operation Guide.<br>
Copyright © 2003 — 2014 ProcessOne</p><p>This document is free software; you can redistribute it and/or
