Ejabberd 1.1.1 Installation and Operation Guide

@@ -32,125 +49,125 @@

I can thoroughly recommend ejabberd for ease of setup -- +
I can thoroughly recommend ejabberd for ease of setup – Kevin Smith, Current maintainer of the Psi project
- + -
Table of Contents
+
Contents
-
+
1  Introduction -
+
1.1  Key Features -
1.2  Additional Features +
1.2  Additional Features
-
2  Installation from Source -
+
2  Installation from Source +
2.1  Installation Requirements -
-2.1.1  ``Unix-like'' operating systems -
2.1.2  Windows +
+2.1.1  “Unix-like” operating systems +
2.1.2  Windows
-
2.2  Obtaining ejabberd -
2.3  Compilation -
-2.3.1  ``Unix-like'' operating systems -
2.3.2  Windows +
2.2  Obtaining ejabberd +
2.3  Compilation +
+2.3.1  “Unix-like” operating systems +
2.3.2  Windows
-
2.4  Starting +
2.4  Starting
-
3  Configuration -
+
3  Configuration +
3.1  Initial Configuration -
+
3.1.1  Host Names -
3.1.2  Default Language -
3.1.3  Access Rules -
3.1.4  Shapers -
3.1.5  Limitation of the number of opened sessions -
3.1.6  Listened Sockets -
3.1.7  Modules -
3.1.8  Virtual Hosting -
3.1.9  SASL anonymous and anonymous login +
3.1.2  Default Language +
3.1.3  Access Rules +
3.1.4  Shapers +
3.1.5  Limitation of the number of opened sessions +
3.1.6  Listened Sockets +
3.1.7  Modules +
3.1.8  Virtual Hosting +
3.1.9  SASL anonymous and anonymous login
-
3.2  Relational Database Support -
+
3.2  Relational Database Support +
3.2.1  Preliminary steps -
3.2.2  Authentication against a relational database -
3.2.3  Relational database for other modules +
3.2.2  Authentication against a relational database +
3.2.3  Relational database for other modules
-
3.3  Creating an Initial Administrator -
3.4  Online Configuration and Monitoring -
+
3.3  Creating an Initial Administrator +
3.4  Online Configuration and Monitoring +
3.4.1  Web Interface -
3.4.2  ejabberdctl +
3.4.2  ejabberdctl

-
4  Firewall Settings -
5  SRV Records -
6  Clustering -
+
4  Firewall Settings +
5  SRV Records +
6  Clustering +
6.1  How it Works -
+
6.1.1  Router -
6.1.2  Local Router -
6.1.3  Session Manager -
6.1.4  s2s Manager +
6.1.2  Local Router +
6.1.3  Session Manager +
6.1.4  s2s Manager
-
6.2  Clustering Setup +
6.2  Clustering Setup
-
A  Built-in Modules -
+
A  Built-in Modules +
A.1  Overview -
A.2  Common Options -
+
A.2  Common Options +
A.2.1  iqdisc -
A.2.2  hosts +
A.2.2  hosts
-
A.3  mod_announce -
A.4  mod_disco -
A.5  mod_echo -
A.6  mod_irc -
A.7  mod_last -
A.8  mod_muc -
A.9  mod_muc_log -
A.10  mod_offline -
A.11  mod_privacy -
A.12  mod_private -
A.13  mod_pubsub -
A.14  mod_register -
A.15  mod_roster -
A.16  mod_service_log -
A.17  mod_shared_roster -
A.18  mod_stats -
A.19  mod_time -
A.20  mod_vcard -
A.21  LDAP and mod_vcard_ldap -
+
A.3  mod_announce +
A.4  mod_disco +
A.5  mod_echo +
A.6  mod_irc +
A.7  mod_last +
A.8  mod_muc +
A.9  mod_muc_log +
A.10  mod_offline +
A.11  mod_privacy +
A.12  mod_private +
A.13  mod_pubsub +
A.14  mod_register +
A.15  mod_roster +
A.16  mod_service_log +
A.17  mod_shared_roster +
A.18  mod_stats +
A.19  mod_time +
A.20  mod_vcard +
A.21  LDAP and mod_vcard_ldap +
A.21.1  Features -
A.21.2  Connection -
A.21.3  Authentication -
A.21.4  vCards and Search -
A.21.5  Examples +
A.21.2  Connection +
A.21.3  Authentication +
A.21.4  vCards and Search +
A.21.5  Examples
-
A.22  mod_version +
A.22  mod_version
-
B  Internationalization and Localization -
C  Release Notes -
+
B  Internationalization and Localization +
C  Release Notes +
C.1  ejabberd 0.9 -
C.2  ejabberd 0.9.1 -
C.3  ejabberd 0.9.8 -
C.4  ejabberd 1.0.0 -
C.5  ejabberd 1.1.0 -
C.6  ejabberd 1.1.1 +
C.2  ejabberd 0.9.1 +
C.3  ejabberd 0.9.8 +
C.4  ejabberd 1.0.0 +
C.5  ejabberd 1.1.0 +
C.6  ejabberd 1.1.1
-
D  Acknowledgements +
D  Acknowledgements
-
1  Introduction
+
1  Introduction
@@ -162,135 +179,135 @@
-
1.1  Key Features
+
1.1  Key Features
ejabberd is: -
+
Multiplatform: ejabberd runs under Microsoft Windows and Unix derived systems such as Linux, FreeBSD and NetBSD.

-
Distributed: You can run ejabberd 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.
+
Distributed: You can run ejabberd 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.

-
Fault-tolerant: You can deploy an ejabberd 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''.
+
Fault-tolerant: You can deploy an ejabberd 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”.

-
Administrator Friendly: ejabberd 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: -
+
Administrator Friendly: ejabberd 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: +
Comprehensive documentation. -
Straightforward installers for Linux, Mac OS X, and Windows. -
Web interface for administration tasks. -
Shared Roster Groups. -
Command line administration tool. -
Can integrate with existing authentication mechanisms. -
Capability to send announce messages. +
Straightforward installers for Linux, Mac OS X, and Windows. +
Web interface for administration tasks. +
Shared Roster Groups. +
Command line administration tool. +
Can integrate with existing authentication mechanisms. +
Capability to send announce messages.

-
Internationalized: ejabberd leads in internationalization. Hence it is very well suited in a globalized world. Related features are: -
+
Internationalized: ejabberd leads in internationalization. Hence it is very well suited in a globalized world. Related features are: +
Translated in 11 languages. -
Support for IDNA. +
Support for IDNA.

-
Open Standards: ejabberd is the first Open Source Jabber server claiming to fully comply to the XMPP standard. -
+
Open Standards: ejabberd is the first Open Source Jabber server claiming to fully comply to the XMPP standard. +
Fully XMPP compliant -
XML-based protocol -
Many JEPs supported. +
XML-based protocol +
Many JEPs supported.
-
1.2  Additional Features
+
1.2  Additional Features
Besides common Jabber server features, ejabberd comes with a wide range of other features: -
+
Modular -
+
Load only the modules you want. -
Extend ejabberd with your own custom modules. +
Extend ejabberd with your own custom modules.
-
Security -
+
Security +
SASL and STARTTLS for c2s and s2s connections. -
STARTTLS and Dialback s2s connections. -
Web interface accessible via HTTPS secure access. +
STARTTLS and Dialback s2s connections. +
Web interface accessible via HTTPS secure access.
-
Databases -
+
Databases +
Native MySQL support. -
Native PostgreSQL support. -
Mnesia. -
ODBC data storage support. -
Microsoft SQL Server support (via ODBC). +
Native PostgreSQL support. +
Mnesia. +
ODBC data storage support. +
Microsoft SQL Server support (via ODBC).
-
Authentication -
+
Authentication +
LDAP and ODBC. -
External Authentication script. -
Internal Authentication. +
External Authentication script. +
Internal Authentication.
-
Others -
+
Others +
Compressing XML streams with Stream Compression (JEP-0138). -
Interface with networks such as AIM, ICQ and MSN. -
Statistics via Statistics Gathering (JEP-0039). -
IPv6 support both for c2s and s2s connections. -
Multi-User Chat module with logging. -
Users Directory based on users vCards. -
Publish-Subscribe component. -
Support for virtual hosting. -
HTTP Polling service. -
IRC transport. +
Interface with networks such as AIM, ICQ and MSN. +
Statistics via Statistics Gathering (JEP-0039). +
IPv6 support both for c2s and s2s connections. +
Multi-User Chat module with logging. +
Users Directory based on users vCards. +
Publish-Subscribe component. +
Support for virtual hosting. +
HTTP Polling service. +
IRC transport.

-
2  Installation from Source
+
2  Installation from Source
-
2.1  Installation Requirements
+
2.1  Installation Requirements
- + -
2.1.1  ``Unix-like'' operating systems
+
2.1.1  “Unix-like” operating systems
-To compile ejabberd on a ``Unix-like'' operating system, you need: -
+To compile ejabberd on a “Unix-like” operating system, you need: +
GNU Make; -
GCC; -
libexpat 1.95 or higher; -
Erlang/OTP R9C-2 or higher; -
OpenSSL 0.9.6 or higher (optional). -
Zlib 1.2.3 or higher (optional). -
GNU Iconv 1.8 or higher (optional, not needed at all on systems with GNU libc). +
GCC; +
libexpat 1.95 or higher; +
Erlang/OTP R9C-2 or higher; +
OpenSSL 0.9.6 or higher (optional). +
Zlib 1.2.3 or higher (optional). +
GNU Iconv 1.8 or higher (optional, not needed at all on systems with GNU libc).
-
2.1.2  Windows
+
2.1.2  Windows
To compile ejabberd on a Windows flavour, you need: -
+
MS Visual C++ 6.0 Compiler -
Erlang/OTP R9C-2 or higher -
Expat 1.95.7 or higher -
GNU Iconv 1.9.1 +
Erlang/OTP R9C-2 or higher +
Expat 1.95.7 or higher +
GNU Iconv 1.9.1 (optional) -
Shining Light OpenSSL +
Shining Light OpenSSL (to enable SSL connections) -
Zlib 1.2.3 or higher +
Zlib 1.2.3 or higher
-
2.2  Obtaining ejabberd
+
2.2  Obtaining ejabberd
@@ -299,49 +316,49 @@ Released versions of ejabberd can be obtained from

The latest development version can be retrieved from the Subversion repository. -
+
svn co http://svn.process-one.net/ejabberd/trunk ejabberd
-
2.3  Compilation
+
2.3  Compilation
- + -
2.3.1  ``Unix-like'' operating systems
+
2.3.1  “Unix-like” operating systems
-Compile ejabberd on a ``Unix-like'' operating system by executing: -
+Compile ejabberd on a “Unix-like” operating system by executing: +
./configure make su make install
These commands will: -
+
install ejabberd into the directory /var/lib/ejabberd, -
install the configuration file into /etc/ejabberd, -
create a directory called /var/log/ejabberd to store log files. +
install the configuration file into /etc/ejabberd, +
create a directory called /var/log/ejabberd to store log files.
-
2.3.2  Windows
+
2.3.2  Windows
-
+
Install Erlang emulator (for example, into C:\Program Files\erl5.3). -
Install Expat library into C:\Program Files\Expat-1.95.7 +
Install Expat library into C:\Program Files\Expat-1.95.7 directory.

Copy file C:\Program Files\Expat-1.95.7\Libs\libexpat.dll to your Windows system directory (for example, C:\WINNT or C:\WINNT\System32) -
Build and install the Iconv library into the directory +
Build and install the Iconv library into the directory C:\Program Files\iconv-1.9.1.

Copy file C:\Program Files\iconv-1.9.1\bin\iconv.dll to your @@ -353,25 +370,25 @@ Note: instead of copying libexpat.dll and iconv.dll to the Windows C:\Program Files\Expat-1.95.7\Libs and C:\Program Files\iconv-1.9.1\bin to the PATH environment variable. -
While in the directory ejabberd\src run: -
+
While in the directory ejabberd\src run: +
configure.bat nmake -f Makefile.win32 -
Edit the file ejabberd\src\ejabberd.cfg and run -
+
Edit the file ejabberd\src\ejabberd.cfg and run +
werl -s ejabberd -name ejabberd
-
2.4  Starting
+
2.4  Starting
Execute the following command to start ejabberd: -
+
erl -pa /var/lib/ejabberd/ebin -name ejabberd -s ejabberd
or -
+
erl -pa /var/lib/ejabberd/ebin -sname ejabberd -s ejabberd
In the latter case the Erlang node will be identified using only the first part of the host name, i. e. other Erlang nodes outside this domain can't contact @@ -383,7 +400,7 @@ for storing its user database and for logging.

To specify the path to the configuration file, the log files and the Mnesia database directory, you may use the following command: -
+
erl -pa /var/lib/ejabberd/ebin \ -sname ejabberd \ -s ejabberd \ @@ -397,25 +414,25 @@ You can find other useful options in the Erlang manual page
To use more than 1024 connections, you should set the environment variable ERL_MAX_PORTS: -
+
export ERL_MAX_PORTS=32000
Note that with this value, ejabberd will use more memory (approximately 6 MB more).

To reduce memory usage, you may set the environment variable ERL_FULLSWEEP_AFTER: -
+
export ERL_FULLSWEEP_AFTER=0
But in this case ejabberd can start to work slower.

-
3  Configuration
+
3  Configuration
-
3.1  Initial Configuration
+
3.1  Initial Configuration
@@ -426,12 +443,12 @@ configuration file are appended to the entries in the database. The configuration file contains a sequence of Erlang terms. Lines beginning with a `%' sign are ignored. Each term is a tuple of which the first element is the name of an option, and any further elements are that option's values. If the -configuration file do not contain for instance the ``hosts'' option, the old +configuration file do not contain for instance the “hosts” option, the old host name(s) stored in the database will be used.

You can override the old values stored in the database by adding next lines to the configuration file: -
+
override_global. override_local. override_acls. @@ -440,7 +457,7 @@ before new ones are added.

-
3.1.1  Host Names
+
3.1.1  Host Names
@@ -448,23 +465,23 @@ The option hosts defines a list containing one or more domains that ejabberd will serve.

Examples: -
+
Serving one domain: -
-
+
+
{hosts, ["example.org"]}. -
Backwards compatibility with older ejabberd versions can be retained +
Backwards compatibility with older ejabberd versions can be retained with: -
+
{host, "example.org"}.
-
Serving two domains: -
+
Serving two domains: +
{hosts, ["example.net", "example.com"]}.
-
3.1.2  Default Language
+
3.1.2  Default Language
@@ -475,82 +492,82 @@ option language is "en". In order to take effect there must be translation file <language>.msg in ejabberd's msgs directory.

Examples: -
+
To set Russian as default language: -
+
{language, "ru"}. -
To set Spanish as default language: -
+
To set Spanish as default language: +
{language, "es"}.
-
3.1.3  Access Rules
+
3.1.3  Access Rules
Access control in ejabberd is performed via Access Control Lists (ACLs). The declarations of ACLs in the configuration file have the following syntax: -
+
{acl, <aclname>, {<acltype>, ...}}.
<acltype> can be one of the following: -
-all
Matches all JIDs. Example: -
+
+all
Matches all JIDs. Example: +
{acl, all, all}. -
{user, <username>}
Matches the user with the name +
{user, <username>}
Matches the user with the name <username> at the first virtual host. Example: -
+
{acl, admin, {user, "yozhik"}}. -
{user, <username>, <server>}
Matches the user with the JID +
{user, <username>, <server>}
Matches the user with the JID <username>@<server> and any resource. Example: -
+
{acl, admin, {user, "yozhik", "example.org"}}. -
{server, <server>}
Matches any JID from server +
{server, <server>}
Matches any JID from server <server>. Example: -
+
{acl, exampleorg, {server, "example.org"}}. -
{user_regexp, <regexp>}
Matches any local user with a name that +
{user_regexp, <regexp>}
Matches any local user with a name that matches <regexp> at the first virtual host. Example: -
+
{acl, tests, {user, "^test[0-9]*$"}}. -
{user_regexp, <regexp>, <server>}
Matches any user with a name +
{user_regexp, <regexp>, <server>}
Matches any user with a name that matches <regexp> at server <server>. Example: -
+
{acl, tests, {user, "^test", "example.org"}}. -
{server_regexp, <regexp>}
Matches any JID from the server that +
{server_regexp, <regexp>}
Matches any JID from the server that matches <regexp>. Example: -
+
{acl, icq, {server, "^icq\\."}}. -
{node_regexp, <user_regexp>, <server_regexp>}
Matches any user +
{node_regexp, <user_regexp>, <server_regexp>}
Matches any user with a name that matches <user_regexp> at any server that matches <server_regexp>. Example: -
+
{acl, yohzik, {node_regexp, "^yohzik$", "^example.(com|org)$"}}. -
{user_glob, <glob>}
-
{user_glob, <glob>, <server>}
-
{server_glob, <glob>}
-
{node_glob, <user_glob>, <server_glob>}
This is the same as +
{user_glob, <glob>}
+
{user_glob, <glob>, <server>}
+
{server_glob, <glob>}
+
{node_glob, <user_glob>, <server_glob>}
This is the same as above. However, it uses shell glob patterns instead of regexp. These patterns can have the following special characters: -
- *
matches any string including the null string. -
?
matches any single character. -
[...]
matches any of the enclosed characters. Character +
+ *
matches any string including the null string. +
?
matches any single character. +
[...]
matches any of the enclosed characters. Character ranges are specified by a pair of characters separated by a `-'. If the first character after `[' is a `!', any character not enclosed is matched.

The following ACLs are pre-defined: -
-all
Matches any JID. -
none
Matches no JID. +
+all
Matches any JID. +
none
Matches no JID.
An entry allowing or denying access to different services looks similar to this: -
+
{access, <accessname>, [{allow, <aclname>}, {deny, <aclname>}, ... @@ -558,57 +575,57 @@ this:
When a JID is checked to have access to <accessname>, the server sequentially checks if that JID mathes any of the ACLs that are named in the second elements of the tuples in the list. If it matches, the first element of -the first matched tuple is returned, otherwise ``deny'' is returned.
+the first matched tuple is returned, otherwise “deny” is returned.

Example: -
+
{access, configure, [{allow, admin}]}. {access, something, [{deny, badmans}, {allow, all}]}.
The following access rules are pre-defined: -
-all
Always returns ``allow'' -
none
Always returns ``deny'' +
+all
Always returns “allow” +
none
Always returns “deny”
-
3.1.4  Shapers
+
3.1.4  Shapers
Shapers enable you to limit connection traffic. The syntax of shapers is like this: -
+
{shaper, <shapername>, <kind>}.
Currently only one kind of shaper called maxrate is available. It has the following syntax: -
+
{maxrate, <rate>}
where <rate> stands for the maximum allowed incomig rate in bytes per second.

Examples: -
-To define a shaper named ``normal'' with traffic speed limited to +
+To define a shaper named “normal” with traffic speed limited to 1,000 bytes/second: -
+
{shaper, normal, {maxrate, 1000}}. -
To define a shaper named ``fast'' with traffic speed limited to +
To define a shaper named “fast” with traffic speed limited to 50,000 bytes/second: -
+
{shaper, fast, {maxrate, 50000}}.
-
3.1.5  Limitation of the number of opened sessions
+
3.1.5  Limitation of the number of opened sessions
This option specifies the maximum number of sessions (authenticated connections) per user. If a user tries to open more than the maximum number of allowed sessions, with different resources, the first opened session will be -disconnected. The error ``session replaced'' is send to the +disconnected. The error “session replaced” is send to the disconnected session. This value is either a number or infinity. For example {max\_user\_sessions, 10}. The default value is 10.

@@ -616,21 +633,21 @@ This option can be define per virtual host. See section 3.1.6  Listened Sockets

Identification	Group ``club_members`'
Displayed groups	`club_members`

Identification	Group ``management`'
`sales`

Ejabberd 1.1.1 Installation and Operation Guide

Ejabberd 1.1.1 Installation and Operation Guide

Alexey Shchepin mailto:alexey@sevcom.net -xmpp:aleksey@jabber.ru

Table of Contents

Contents

1 Introduction

1 Introduction

1.1 Key Features

1.1 Key Features

1.2 Additional Features

1.2 Additional Features

2 Installation from Source

2 Installation from Source

2.1 Installation Requirements

2.1 Installation Requirements

2.1.1 ``Unix-like'' operating systems

2.1.1 “Unix-like” operating systems

2.1.2 Windows

2.1.2 Windows

2.2 Obtaining ejabberd

2.2 Obtaining ejabberd

2.3 Compilation

2.3 Compilation

2.3.1 ``Unix-like'' operating systems

2.3.1 “Unix-like” operating systems

2.3.2 Windows

2.3.2 Windows

2.4 Starting

2.4 Starting

3 Configuration

3 Configuration

3.1 Initial Configuration

3.1 Initial Configuration

3.1.1 Host Names

3.1.1 Host Names

3.1.2 Default Language

3.1.2 Default Language

3.1.3 Access Rules

3.1.3 Access Rules

3.1.4 Shapers

3.1.4 Shapers

3.1.5 Limitation of the number of opened sessions

3.1.5 Limitation of the number of opened sessions

3.1.6 Listened Sockets

3.1.7 Modules

3.1.7 Modules

3.1.8 Virtual Hosting

3.1.8 Virtual Hosting

3.1.9 SASL anonymous and anonymous login

3.1.9 SASL anonymous and anonymous login

3.2 Relational Database Support

3.2 Relational Database Support

3.2.1 Preliminary steps

3.2.1 Preliminary steps

3.2.2 Authentication against a relational database

3.2.2 Authentication against a relational database

3.2.3 Relational database for other modules

3.3 Creating an Initial Administrator

3.3 Creating an Initial Administrator

3.4 Online Configuration and Monitoring

3.4 Online Configuration and Monitoring

3.4.1 Web Interface

3.4.1 Web Interface

3.4.2 ejabberdctl

3.4.2 ejabberdctl

4 Firewall Settings

4 Firewall Settings

5 SRV Records

5 SRV Records

6 Clustering

6 Clustering

6.1 How it Works

6.1 How it Works

6.1.1 Router

6.1.1 Router

6.1.2 Local Router

6.1.2 Local Router

6.1.3 Session Manager

6.1.3 Session Manager

6.1.4 s2s Manager

Alexey Shchepin
`mailto:alexey@sevcom.net`
-`xmpp:aleksey@jabber.ru`

2.2 Obtaining `ejabberd`

2.2 Obtaining `ejabberd`

3.4.2 `ejabberdctl`

3.4.2 `ejabberdctl`

A.2.1 `iqdisc`

A.2.1 `iqdisc`

A.2.2 `hosts`

A.2.2 `hosts`

A.3 `mod_announce`

A.3 `mod_announce`

A.4 `mod_disco`

A.4 `mod_disco`

A.5 `mod_echo`

A.5 `mod_echo`

A.6 `mod_irc`

A.6 `mod_irc`

A.7 `mod_last`

A.7 `mod_last`

A.8 `mod_muc`

A.8 `mod_muc`

A.9 `mod_muc_log`

A.9 `mod_muc_log`

A.10 `mod_offline`

A.10 `mod_offline`

A.11 `mod_privacy`

A.11 `mod_privacy`

A.12 `mod_private`

A.12 `mod_private`

A.13 `mod_pubsub`

A.13 `mod_pubsub`

A.14 `mod_register`

A.14 `mod_register`

A.15 `mod_roster`

A.15 `mod_roster`

A.16 `mod_service_log`

A.16 `mod_service_log`

A.17 `mod_shared_roster`

A.17 `mod_shared_roster`

A.18 `mod_stats`

A.18 `mod_stats`

A.19 `mod_time`

A.19 `mod_time`

A.20 `mod_vcard`

A.20 `mod_vcard`

A.21 LDAP and `mod_vcard_ldap`

A.21 LDAP and `mod_vcard_ldap`

A.22 `mod_version`

A.22 `mod_version`