From 529ab22a79366962dd9da58b277211a57f7e7331 Mon Sep 17 00:00:00 2001 From: Badlop Date: Tue, 31 May 2011 10:14:19 +0200 Subject: [PATCH] Recompile the Guide --- doc/dev.html | 6 +- doc/features.html | 4 +- doc/guide.html | 312 ++++++++++++++++++++++++++-------------------- doc/version.tex | 2 +- 4 files changed, 185 insertions(+), 139 deletions(-) diff --git a/doc/dev.html b/doc/dev.html index b7fea526a..bad9c21d3 100644 --- a/doc/dev.html +++ b/doc/dev.html @@ -2,7 +2,7 @@ "http://www.w3.org/TR/REC-html40/loose.dtd"> -Ejabberd 2.1.x Developers Guide +<TITLE>Ejabberd 2.1.7 Developers Guide @@ -49,7 +49,7 @@ TD P{margin:0px;}

-

Ejabberd 2.1.x Developers Guide

Alexey Shchepin
+

Ejabberd 2.1.7 Developers Guide

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

@@ -170,7 +170,7 @@ manager.

name. If destination JID has a non-empty user part, then it routed to the session manager, else it is processed depending on it’s content.

3.3  Session Manager

This module routes packets to local users. It searches for what user resource -packet must be sended via presence table. If this resource is connected to +packet must be sent via presence table. If this resource is connected to this node, it is routed to C2S process, if it connected via another node, then the packet is sent to session manager on that node.

3.4  S2S Manager

This module routes packets to other XMPP servers. First, it checks if an diff --git a/doc/features.html b/doc/features.html index 503ac0d3f..f9b6bec58 100644 --- a/doc/features.html +++ b/doc/features.html @@ -2,7 +2,7 @@ "http://www.w3.org/TR/REC-html40/loose.dtd"> -Ejabberd 2.1.x Feature Sheet +<TITLE>Ejabberd 2.1.7 Feature Sheet @@ -50,7 +50,7 @@ SPAN{width:20%; float:right; text-align:left; margin-left:auto;}

-

Ejabberd 2.1.x Feature Sheet

Sander Devrieze
+

Ejabberd 2.1.7 Feature Sheet

Sander Devrieze
mailto:s.devrieze@pandora.be
xmpp:sander@devrieze.dyndns.org

diff --git a/doc/guide.html b/doc/guide.html index a38e9b293..24bb2d306 100644 --- a/doc/guide.html +++ b/doc/guide.html @@ -6,7 +6,7 @@ - ejabberd 2.1.x + ejabberd 2.1.7 Installation and Operation Guide @@ -76,7 +76,7 @@ BLOCKQUOTE.figure DIV.center DIV.center HR{display:none;}


- +
ejabberd 2.1.x
ejabberd 2.1.7
 
Installation and Operation Guide

@@ -151,76 +151,77 @@ BLOCKQUOTE.figure DIV.center DIV.center HR{display:none;}
  • 3.3.11  mod_muc_log
  • 3.3.12  mod_offline
  • 3.3.13  mod_ping -
  • 3.3.14  mod_privacy -
  • 3.3.15  mod_private -
  • 3.3.16  mod_proxy65 -
  • 3.3.17  mod_pubsub -
  • 3.3.18  mod_register -
  • 3.3.19  mod_register_web -
  • 3.3.20  mod_roster -
  • 3.3.21  mod_service_log -
  • 3.3.22  mod_shared_roster -
  • 3.3.23  mod_shared_roster_ldap -
  • 3.3.24  mod_sic -
  • 3.3.25  mod_stats -
  • 3.3.26  mod_time -
  • 3.3.27  mod_vcard -
  • 3.3.28  mod_vcard_ldap -
  • 3.3.29  mod_vcard_xupdate -
  • 3.3.30  mod_version +
  • 3.3.14  mod_pres_counter +
  • 3.3.15  mod_privacy +
  • 3.3.16  mod_private +
  • 3.3.17  mod_proxy65 +
  • 3.3.18  mod_pubsub +
  • 3.3.19  mod_register +
  • 3.3.20  mod_register_web +
  • 3.3.21  mod_roster +
  • 3.3.22  mod_service_log +
  • 3.3.23  mod_shared_roster +
  • 3.3.24  mod_shared_roster_ldap +
  • 3.3.25  mod_sic +
  • 3.3.26  mod_stats +
  • 3.3.27  mod_time +
  • 3.3.28  mod_vcard +
  • 3.3.29  mod_vcard_ldap +
  • 3.3.30  mod_vcard_xupdate +
  • 3.3.31  mod_version
    • -
  • Chapter 4  Managing an ejabberd Server +
  • Chapter 4  Managing an ejabberd Server -
  • Chapter 5  Securing ejabberd +
  • Chapter 5  Securing ejabberd -
  • Chapter 6  Clustering +
  • Chapter 6  Clustering -
  • Chapter 7  Debugging +
  • Chapter 7  Debugging -
  • Appendix A  Internationalization and Localization -
  • Appendix B  Release Notes -
  • Appendix C  Acknowledgements -
  • Appendix D  Copyright Information +
  • Appendix A  Internationalization and Localization +
  • Appendix B  Release Notes +
  • Appendix C  Acknowledgements +
  • Appendix D  Copyright Information

    • Chapter 1  Introduction

    ejabberd is a free and open source instant messaging server written in Erlang/OTP.

    ejabberd is cross-platform, distributed, fault-tolerant, and based on open standards to achieve real-time communication.

    ejabberd is designed to be a rock-solid and feature rich XMPP server.

    ejabberd is suitable for small deployments, whether they need to be scalable or not, as well as extremely big deployments.

    @@ -521,7 +522,7 @@ There are two ways to register a XMPP account:
    1. Using ejabberdctl (see section 4.1): 
      ejabberdctl register admin1 example.org FgT5bk3
-
    2. Using a XMPP client and In-Band Registration (see section 3.3.18). +
    3. Using a XMPP client and In-Band Registration (see section 3.3.19).
  • Edit the ejabberd configuration file to give administration rights to the XMPP account you created: 
    {acl, admins, {user, "admin1", "example.org"}}.
@@ -881,7 +882,7 @@ and also allows plain connections for old clients.
  • Port 5269 listens for s2s connections with STARTTLS. The socket is set for IPv6 instead of IPv4.
  • Port 3478 listens for STUN requests over UDP.
  • Port 5280 listens for HTTP requests, and serves the HTTP Poll service. -
  • Port 5281 listens for HTTP requests, and serves the Web Admin using HTTPS as explained in +
  • Port 5281 listens for HTTP requests, using HTTPS to serve HTTP-Bind (BOSH) and the Web Admin as explained in section 4.3. The socket only listens connections to the IP address 127.0.0.1. 
    • {hosts, ["example.com", "example.org", "example.net"]}.
 {listen,
@@ -908,6 +909,7 @@ section 4.3. The socket only listens connections to
                         ]},
   {{5281, "127.0.0.1"}, ejabberd_http, [
                                         web_admin,
+                                        http_bind,
                                         tls, {certfile, "/etc/ejabberd/server.pem"},
                                        ]}
  ]
@@ -1218,7 +1220,7 @@ matches Regexp. Example:
    {node_regexp, UserRegexp, ServerRegexp}
    Matches any user with a name that matches UserRegexp at any server that matches ServerRegexp. Example: -
    {acl, yohzik, {node_regexp, "^yohzik$", "^example.(com|org)$"}}.
+
    {acl, yozhik, {node_regexp, "^yozhik$", "^example.(com|org)$"}}.
    {user_glob, Glob}
    {user_glob, Glob, Server}
    {server_glob, Glob}
    @@ -1316,17 +1318,22 @@ using ImageMagick’s Convert program.

    The configurable options are: {captcha_cmd, Path}

    Full path to a script that generates the image. The default value is an empty string: "" -
    {captcha_host, Host}
    -Host part of the URL sent to the user. -You can include the port number. -The URL sent to the user is formed by: http://Host/captcha/ -The default value is the first hostname configured. +
    {captcha_host, ProtocolHostPort}
    +ProtocolHostPort is a string with the host, and optionally the Protocol and Port number. +It must identify where ejabberd listens for CAPTCHA requests. +The URL sent to the user is formed by: Protocol://Host:Port/captcha/ +The default value is: protocol http, the first hostname configured, and port 80. +If you specify a port number that does not match exactly an ejabberd listener +(because you are using a reverse proxy or other port-forwarding tool), +then you must specify the transfer protocol, as seen in the example below.

    Additionally, an ejabberd_http listener must be enabled with the captcha option. See section 3.1.3.

    Example configuration: 

    {hosts, ["example.org"]}.
 
 {captcha_cmd, "/lib/ejabberd/priv/bin/captcha.sh"}.
 {captcha_host, "example.org:5280"}.
+%% {captcha_host, "https://example.org:443"}.
+%% {captcha_host, "http://example.com"}.
 
 {listen,
  [
@@ -1464,6 +1471,7 @@ different storage systems for modules, and so forth.
    The following databas
 Active Directory
 (see section 3.2.5)
 
  • OpenLDAP
+
  • CommuniGate Pro
 
  • Normally any LDAP compatible server should work; inform us about your
 success with a not-listed server so that we can list it here.
 
    • Important note about virtual hosting:
@@ -1908,6 +1916,7 @@ all entries end with a comma:
 
+
@@ -1922,8 +1931,9 @@ all entries end with a comma:
 
-
-
+
+
+
@@ -1985,7 +1995,8 @@ these queries.
    The syntax is:
 
    {iqdisc, Value}
    Possible Value are:
 
    
 no_queue
     All queries of a namespace with this processing discipline are
-processed immediately. This also means that no other packets can be processed
+processed directly. This means that the XMPP connection that sends this IQ query gets blocked:
+no other packets can be processed
 until this one has been completely processed. Hence this discipline is not
 recommended if the processing of a query can take a relatively long time.
 
    one_queue
     In this case a separate queue is created for the processing
@@ -1993,7 +2004,7 @@ of IQ queries of a namespace with this discipline. In addition, the processing
 of this queue is done in parallel with that of other packets. This discipline
 is most recommended.
 
    {queues, N}
     N separate queues are created to process the
-queries. The queries are thus process in parallel, but in a
+queries. The queries are thus processed in parallel, but in a
 controlled way.
 
    parallel
     For every packet with this discipline a separate Erlang process
 is spawned. Consequently, all these packets are processed in parallel.
@@ -2327,7 +2338,7 @@ to the IRC transport instead of the Multi-User Chat service.
 to join a channel, and to set custom IRC username and encoding.
 
  • When using a popular XMPP server, it can occur that no
 connection can be achieved with some IRC servers because they limit the
-number of conections from one IP.
+number of connections from one IP.
 
    • Options:
 
    
 
@@ -2782,8 +2793,33 @@ and if a client does not answer to the ping in less than 32 seconds, its connect
   {mod_ping,  [{send_pings, true}, {ping_interval, 240}, {timeout_action, kill}]},
   ...
  ]}.
+
      
    
+
    3.3.14  mod_pres_counter
      
+
    This module detects flood/spam in presence subscription stanza traffic.
+If a user sends or receives more of those stanzas in a time interval,
+the exceeding stanzas are silently dropped, and warning is logged.
    Configuration options:
+
    
+{count, StanzaNumber}
    
+The number of subscription presence stanzas
+(subscribe, unsubscribe, subscribed, unsubscribed)
+allowed for any direction (input or output)
+per time interval.
+Please note that two users subscribing to each other usually generate
+4 stanzas, so the recommended value is 4 or more.
+The default value is: 5.
+
    {interval, Seconds}
    
+The time interval defined in seconds.
+The default value is 60.
+
    This example enables the module, and allows up to 5 presence subscription stanzas
+to be sent or received by the users in 60 seconds:
+
    {modules,
+ [
+  ...
+  {mod_pres_counter,  [{count, 5}, {interval, 60}]},
+  ...
+ ]}.
 
      
    
-
    3.3.14  mod_privacy
      
+
    3.3.15  mod_privacy
      
 
    This module implements Blocking Communication (also known as Privacy Rules)
 as defined in section 10 from XMPP IM. If end users have support for it in
 their XMPP client, they will be able to:
@@ -2811,7 +2847,7 @@ subscription type (or globally).
 {iqdisc, Discipline}
     This specifies
 the processing discipline for Blocking Communication (jabber:iq:privacy) IQ queries (see section 3.3.2).
 
      
    
-
    3.3.15  mod_private
      
+
    3.3.16  mod_private
      
 
    This module adds support for Private XML Storage (XEP-0049):
 
    
 Using this method, XMPP entities can store private data on the server and
@@ -2823,7 +2859,7 @@ of client-specific preferences; another is Bookmark Storage ( This specifies
 the processing discipline for Private XML Storage (jabber:iq:private) IQ queries (see section 3.3.2).
 
      
    
-
    3.3.16  mod_proxy65
      
+
    3.3.17  mod_proxy65
      
 
    This module implements SOCKS5 Bytestreams (XEP-0065).
 It allows ejabberd to act as a file transfer proxy between two
 XMPP clients.
    Options:
@@ -2887,7 +2923,7 @@ The simpliest configuration of the module:
   ...
  ]}.
 
      
    
-
    3.3.17  mod_pubsub
      
+
    3.3.18  mod_pubsub
      
 
    This module offers a Publish-Subscribe Service (XEP-0060).
 The functionality in mod_pubsub can be extended using plugins.
 The plugin that implements PEP (Personal Eventing via Pubsub) (XEP-0163)
@@ -2965,7 +3001,7 @@ with ODBC usage:
   ...
  ]}.
 
      
    
-
    3.3.18  mod_register
      
+
    3.3.19  mod_register
      
 
    This module adds support for In-Band Registration (XEP-0077). This protocol
 enables end users to use a XMPP client to:
 
    • 
@@ -2974,10 +3010,11 @@ Register a new account on the server.
 
    • Delete an existing account on the server.
 
    Options:
 
    
-{access, AccessName}
     This option can be configured to specify
-rules to restrict registration. If a rule returns ‘deny’ on the requested
-user name, registration for that user name is denied. (there are no
-restrictions by default).
+{access, AccessName}
     
+Specify rules to restrict what usernames can be registered and unregistered.
+If a rule returns ‘deny’ on the requested username,
+registration and unregistration of that user name is denied.
+There are no restrictions by default.
 
    {access_from, AccessName}
     By default, ejabberd
 doesn’t allow to register new accounts from s2s or existing c2s sessions. You can
 change it by defining access rule in this option. Use with care: allowing registration
@@ -3066,7 +3103,7 @@ Also define a registration timeout of one hour:
   ...
  ]}.
 
      
    
-
    3.3.19  mod_register_web
      
+
    3.3.20  mod_register_web
      
 
    This module provides a web page where people can:
 
    • 
 Register a new account on the server.
@@ -3097,7 +3134,7 @@ list of JIDs which will be notified each time a new account is registered.
 
      The users can visit this page: https://localhost:5281/register/
 It is important to include the last / character in the URL,
 otherwise the subpages URL will be incorrect.
        
      
-
      3.3.20  mod_roster
        
+
      3.3.21  mod_roster
        
 
      This module implements roster management as defined in
 RFC 3921: XMPP IM.
 It also supports Roster Versioning (XEP-0237).
      Options:
@@ -3124,7 +3161,7 @@ you must disable this option.
   ...
  ]}.
 
        
      
-
      3.3.21  mod_service_log
        
+
      3.3.22  mod_service_log
        
 
      This module adds support for logging end user packets via a XMPP message
 auditing service such as
 Bandersnatch. All user
@@ -3154,7 +3191,7 @@ To log all end user packets to the Bandersnatch service running on
   ...
  ]}.
 
      
    
-
    3.3.22  mod_shared_roster
      
+
    3.3.23  mod_shared_roster
      
 
    This module enables you to create shared roster groups. This means that you can
 create groups of people that can see members from (other) groups in their
 rosters. The big advantages of this feature are that end users do not need to
@@ -3168,11 +3205,13 @@ has a unique identification and the following parameters:
 Name
     The name of the group, which will be displayed in the roster.
 
    Description
     The description of the group. This parameter does not affect
 anything.
-
    Members
     A list of full JIDs of group members, entered one per line in
+
    Members
     A list of JIDs of group members, entered one per line in
 the Web Admin.
-To put as members all the registered users in the virtual hosts,
-you can use the special directive: @all@.
-Note that this directive is designed for a small server with just a few hundred users.
+The special member directive @all@
+represents all the registered users in the virtual host;
+which is only recommended for a small server with just a few hundred users.
+The special member directive @online@
+represents the online users in the virtual host.
 
    Displayed groups
     A list of groups that will be in the rosters of this
 group’s members.
 
    Examples:
@@ -3229,7 +3268,7 @@ roster groups as shown in the following table:
 
    ModuleFeatureDependencies
    
 
    mod_adhocAd-Hoc Commands (XEP-0050) 
    
 
    mod_announceManage announcementsrecommends mod_adhoc
    mod_blockingSimple Communications Blocking (XEP-0191)mod_privacy
    
 
    mod_capsEntity Capabilities (XEP-0115) 
    
 
    mod_configureServer configuration using Ad-Hocmod_adhoc
    
 
    mod_discoService Discovery (XEP-0030) 
    mod_offlineOffline message storage (XEP-0160) 
    
 
    mod_offline_odbcOffline message storage (XEP-0160)supported DB (*)
    
 
    mod_pingXMPP Ping and periodic keepalives (XEP-0199) 
    mod_privacyBlocking Communication (XMPP IM) 
    mod_privacy_odbcBlocking Communication (XMPP IM)supported DB (*)
    mod_privacyDetect presence subscription flood 
    mod_privacyBlocking Communication (XEP-0016) 
    mod_privacy_odbcBlocking Communication (XEP-0016)supported DB (*)
    
 
    mod_privatePrivate XML Storage (XEP-0049) 
    
 
    mod_private_odbcPrivate XML Storage (XEP-0049)supported DB (*)
    
 
    mod_proxy65SOCKS5 Bytestreams (XEP-0065) 

    -

    3.3.23  mod_shared_roster_ldap

    +

    3.3.24  mod_shared_roster_ldap

    This module lets the server administrator automatically populate users’ rosters (contact lists) with entries based on users and groups defined in an LDAP-based directory.

    @@ -3277,7 +3316,7 @@ filter="(&(?=undefined)(?=undefined)(something=else))"

    Attributes

    These parameters specify the names of the attributes which hold interesting data in the entries returned by running filters specified in -section 3.3.23.

    +section 3.3.24.

    ldap_groupattr
    The name of the attribute that holds the group name, and that is used to differentiate between them. Retrieved from results of the “Roster Filter” and “Group Filter”. @@ -3309,7 +3348,7 @@ A globbing format for extracting user ID from the value of the attribute named b ldap_memberattr. Defaults to %u, which means that the whole value is the member ID. If you change it to something different, you may also need to specify the User -and Group Filters manually — see section 3.3.23.
    ldap_memberattr_format_re
    +and Group Filters manually — see section 3.3.24.
    ldap_memberattr_format_re
    A regex for extracting user ID from the value of the attribute named by ldap_memberattr.

    An example value "CN=(\\w*),(OU=.*,)*DC=company,DC=com" works for user IDs such as the following:

    • @@ -3326,17 +3365,17 @@ the option is unset, then instead of a regular expression, a simple format specified by ldap_memberattr_format is used. Also, in the last two cases an error message is logged during the module initialization.

      Also, note that in all cases ldap_memberattr_format (and not the regex version) is used for constructing the default “User/Group Filter” — -see section 3.3.23.

    ldap_auth_check
    +see section 3.3.24.

    ldap_auth_check
    Whether the module should check (via the ejabberd authentication subsystem) for existence of each user in the shared LDAP roster. See -section 3.3.23 form more information. Set to off if you +section 3.3.24 form more information. Set to off if you want to disable the check. Defaults to on.
    ldap_user_cache_validity
    Number of seconds for which the cache for roster item full names is considered -fresh after retrieval. 300 by default. See section 3.3.23 on +fresh after retrieval. 300 by default. See section 3.3.24 on how it is used during roster retrieval.
    ldap_group_cache_validity
    Number of seconds for which the cache for group membership is considered -fresh after retrieval. 300 by default. See section 3.3.23 on +fresh after retrieval. 300 by default. See section 3.3.24 on how it is used during roster retrieval.

    Connection parameters

    The module also accepts the connection parameters, all of which default to the @@ -3446,14 +3485,14 @@ the roster shown in figure 3.4.

    -

    3.3.24  mod_sic

    +

    3.3.25  mod_sic

    This module adds support for Server IP Check (XEP-0279). This protocol enables a client to discover its external IP address.

    Options:

    {iqdisc, Discipline}
    This specifies the processing discipline for urn:xmpp:sic:0 IQ queries (see section 3.3.2).

    -

    3.3.25  mod_stats

    +

    3.3.26  mod_stats

    This module adds support for Statistics Gathering (XEP-0039). This protocol allows you to retrieve next statistics from your ejabberd deployment:

    • @@ -3485,14 +3524,14 @@ by sending: </query> </iq>

    -

    3.3.26  mod_time

    +

    3.3.27  mod_time

    This module features support for Entity Time (XEP-0202). By using this XEP, you are able to discover the time at another entity’s location.

    Options:

    {iqdisc, Discipline}
    This specifies the processing discipline for Entity Time (jabber:iq:time) IQ queries (see section 3.3.2).

    -

    3.3.27  mod_vcard

    +

    3.3.28  mod_vcard

    This module allows end users to store and retrieve their vCard, and to retrieve other users vCards, as defined in vcard-temp (XEP-0054). The module also implements an uncomplicated Jabber User Directory based on the vCards of @@ -3547,7 +3586,7 @@ and that all virtual hosts will be searched instead of only the current one: ... ]}.

    -

    3.3.28  mod_vcard_ldap

    +

    3.3.29  mod_vcard_ldap

    ejabberd can map LDAP attributes to vCard fields. This behaviour is implemented in the mod_vcard_ldap module. This module does not depend on the authentication method (see 3.2.5).

    Usually ejabberd treats LDAP as a read-only storage: @@ -3729,7 +3768,7 @@ searching his info in LDAP.

  • ldap_vcard_map

    • -

    3.3.29  mod_vcard_xupdate

    +

    3.3.30  mod_vcard_xupdate

    The user’s client can store an avatar in the user vCard. The vCard-Based Avatars protocol (XEP-0153) provides a method for clients to inform the contacts what is the avatar hash value. @@ -3743,7 +3782,7 @@ and each presence sent by a client produces hash retrieval and a presence stanza rewrite. For this reason, enabling this module will introduce a computational overhead in servers with clients that change frequently their presence.

    -

    3.3.30  mod_version

    +

    3.3.31  mod_version

    This module implements Software Version (XEP-0092). Consequently, it answers ejabberd’s version when queried.

    Options:

    @@ -3752,8 +3791,8 @@ The default value is true.
    {iqdisc, Discipline}
    This specifies the processing discipline for Software Version (jabber:iq:version) IQ queries (see section 3.3.2).

    -

    Chapter 4  Managing an ejabberd Server

    -

    4.1  ejabberdctl

    With the ejabberdctl command line administration script +

    Chapter 4  Managing an ejabberd Server

    +

    4.1  ejabberdctl

    With the ejabberdctl command line administration script you can execute ejabberdctl commands (described in the next section, 4.1.1) and also many general ejabberd commands (described in section 4.2). This means you can start, stop and perform many other administrative tasks @@ -3765,7 +3804,7 @@ and other codes may be used for specific results. This can be used by other scripts to determine automatically if a command succeeded or failed, for example using: echo $?

    -

    4.1.1  ejabberdctl Commands

    When ejabberdctl is executed without any parameter, +

    4.1.1  ejabberdctl Commands

    When ejabberdctl is executed without any parameter, it displays the available options. If there isn’t an ejabberd server running, the available parameters are:

    @@ -3801,7 +3840,7 @@ robot1 testuser1 testuser2

    -

    4.1.2  Erlang Runtime System

    ejabberd is an Erlang/OTP application that runs inside an Erlang runtime system. +

    4.1.2  Erlang Runtime System

    ejabberd is an Erlang/OTP application that runs inside an Erlang runtime system. This system is configured using environment variables and command line parameters. The ejabberdctl administration script uses many of those possibilities. You can configure some of them with the file ejabberdctl.cfg, @@ -3847,6 +3886,9 @@ This is only useful if you plan to setup an ejabberd cluster with nodes If using -sname, specify either this option or ERL_INETRC.

    -kernel inet_dist_listen_min 4200 inet_dist_listen_min 4210
    Define the first and last ports that epmd (section 5.2) can listen to. +
    -kernel inet_dist_use_interface "{ 127,0,0,1 }"
    + Define the IP address where this Erlang node listens for other nodes +connections (see section 5.2).
    -detached
    Starts the Erlang system detached from the system console. Useful for running daemons and backgrounds processes. @@ -3878,7 +3920,7 @@ not “Simple Authentication and Security Layer”.

    Note that some characters need to be escaped when used in shell scripts, for instance " and {}. You can find other options in the Erlang manual page (erl -man erl).

    -

    4.2  ejabberd Commands

    An ejabberd command is an abstract function identified by a name, +

    4.2  ejabberd Commands

    An ejabberd command is an abstract function identified by a name, with a defined number and type of calling arguments and type of result that is registered in the ejabberd_commands service. Those commands can be defined in any Erlang module and executed using any valid frontend.

    ejabberd includes a frontend to execute ejabberd commands: the script ejabberdctl. @@ -3886,7 +3928,7 @@ Other known frontends that can be installed to execute ejabberd commands in diff ejabberd_xmlrpc (XML-RPC service), mod_rest (HTTP POST service), mod_shcommands (ejabberd WebAdmin page).

    -

    4.2.1  List of ejabberd Commands

    ejabberd includes a few ejabberd Commands by default. +

    4.2.1  List of ejabberd Commands

    ejabberd includes a few ejabberd Commands by default. When more modules are installed, new commands may be available in the frontends.

    The easiest way to get a list of the available commands, and get help for them is to use the ejabberdctl script: 

    $ ejabberdctl help
@@ -3938,7 +3980,7 @@ is very high.
 
    register user host password
     Register an account in that domain with the given password.
 
    unregister user host
     Unregister the given account.

    -

    4.2.2  Restrict Execution with AccessCommands

    The frontends can be configured to restrict access to certain commands. +

    4.2.2  Restrict Execution with AccessCommands

    The frontends can be configured to restrict access to certain commands. In that case, authentication information must be provided. In each frontend the AccessCommands option is defined in a different place. But in all cases the option syntax is the same: @@ -3983,7 +4025,7 @@ and the provided arguments do not contradict Arguments.

    As an example to u {_bot_reg_test, [register, unregister], [{host, "test.org"}]} ]

    -

    4.3  Web Admin

    +

    4.3  Web Admin

    The ejabberd Web Admin allows to administer most of ejabberd using a web browser.

    This feature is enabled by default: a ejabberd_http listener with the option web_admin (see section 3.1.3) is included in the listening ports. Then you can open @@ -4060,13 +4102,13 @@ The file is searched by default in The directory of the documentation can be specified in the environment variable EJABBERD_DOC_PATH. See section 4.1.2.

    -

    4.4  Ad-hoc Commands

    If you enable mod_configure and mod_adhoc, +

    4.4  Ad-hoc Commands

    If you enable mod_configure and mod_adhoc, you can perform several administrative tasks in ejabberd with a XMPP client. The client must support Ad-Hoc Commands (XEP-0050), and you must login in the XMPP server with an account with proper privileges.

    -

    4.5  Change Computer Hostname

    ejabberd uses the distributed Mnesia database. +

    4.5  Change Computer Hostname

    ejabberd uses the distributed Mnesia database. Being distributed, Mnesia enforces consistency of its file, so it stores the name of the Erlang node in it (see section 5.4). The name of an Erlang node includes the hostname of the computer. @@ -4112,8 +4154,8 @@ mv /var/lib/ejabberd/*.* /var/lib/ejabberd/oldfiles/

  • Check that the information of the old database is available: accounts, rosters... After you finish, remember to delete the temporary backup files from public directories.

    • -

    Chapter 5  Securing ejabberd

    -

    5.1  Firewall Settings

    +

    Chapter 5  Securing ejabberd

    +

    5.1  Firewall Settings

    You need to take the following TCP ports in mind when configuring your firewall:

    @@ -4124,7 +4166,7 @@ After you finish, remember to delete the temporary backup files from public dire
    PortDescription
    port rangeUsed for connections between Erlang nodes. This range is configurable (see section 5.2).

    -

    5.2  epmd

    epmd (Erlang Port Mapper Daemon) +

    5.2  epmd

    epmd (Erlang Port Mapper Daemon) is a small name server included in Erlang/OTP and used by Erlang programs when establishing distributed Erlang communications. ejabberd needs epmd to use ejabberdctl and also when clustering ejabberd nodes. @@ -4148,8 +4190,12 @@ The ports used in this case by default are random, but can be configured in the file ejabberdctl.cfg. The Erlang command-line parameter used internally is, for example: 

    erl ... -kernel inet_dist_listen_min 4370 inet_dist_listen_max 4375
+

    It is also possible to configure in ejabberdctl.cfg +the network interface where the Erlang node will listen and accept connections. +The Erlang command-line parameter used internally is, for example: +

    erl ... -kernel inet_dist_use_interface "{127,0,0,1}"

    -

    5.3  Erlang Cookie

    The Erlang cookie is a string with numbers and letters. +

    5.3  Erlang Cookie

    The Erlang cookie is a string with numbers and letters. An Erlang node reads the cookie at startup from the command-line parameter -setcookie. If not indicated, the cookie is read from the cookie file $HOME/.erlang.cookie. If this file does not exist, it is created immediately with a random cookie. @@ -4163,7 +4209,7 @@ to prevent unauthorized access or intrusion to an Erlang node. The communication between Erlang nodes are not encrypted, so the cookie could be read sniffing the traffic on the network. The recommended way to secure the Erlang node is to block the port 4369.

    -

    5.4  Erlang Node Name

    An Erlang node may have a node name. +

    5.4  Erlang Node Name

    An Erlang node may have a node name. The name can be short (if indicated with the command-line parameter -sname) or long (if indicated with the parameter -name). Starting an Erlang node with -sname limits the communication between Erlang nodes to the LAN.

    Using the option -sname instead of -name is a simple method @@ -4172,7 +4218,7 @@ However, it is not ultimately effective to prevent access to the Erlang node, because it may be possible to fake the fact that you are on another network using a modified version of Erlang epmd. The recommended way to secure the Erlang node is to block the port 4369.

    -

    5.5  Securing Sensitive Files

    ejabberd stores sensitive data in the file system either in plain text or binary files. +

    5.5  Securing Sensitive Files

    ejabberd stores sensitive data in the file system either in plain text or binary files. The file system permissions should be set to only allow the proper user to read, write and execute those files and directories.

    ejabberd configuration file: /etc/ejabberd/ejabberd.cfg
    @@ -4192,9 +4238,9 @@ so it is preferable to secure the whole /var/lib/ejabberd/ directory.
    Erlang cookie file: /var/lib/ejabberd/.erlang.cookie
    See section 5.3.

    -

    Chapter 6  Clustering

    +

    Chapter 6  Clustering

    -

    6.1  How it Works

    +

    6.1  How it Works

    A XMPP domain is served by one or more ejabberd nodes. These nodes can be run on different machines that are connected via a network. They all must have the ability to connect to port 4369 of all another nodes, and must @@ -4208,29 +4254,29 @@ router,

  • session manager,
  • s2s manager.

    • -

    6.1.1  Router

    +

    6.1.1  Router

    This module is the main router of XMPP packets on each node. It routes them based on their destination’s domains. It uses a global routing table. The domain of the packet’s destination is searched in the routing table, and if it is found, the packet is routed to the appropriate process. If not, it is sent to the s2s manager.

    -

    6.1.2  Local Router

    +

    6.1.2  Local Router

    This module routes packets which have a destination domain equal to one of this server’s host names. If the destination JID has a non-empty user part, it is routed to the session manager, otherwise it is processed depending on its content.

    -

    6.1.3  Session Manager

    +

    6.1.3  Session Manager

    This module routes packets to local users. It looks up to which user resource a packet must be sent via a presence table. Then the packet is either routed to the appropriate c2s process, or stored in offline storage, or bounced back.

    -

    6.1.4  s2s Manager

    +

    6.1.4  s2s Manager

    This module routes packets to other XMPP servers. First, it checks if an opened s2s connection from the domain of the packet’s source to the domain of the packet’s destination exists. If that is the case, the s2s manager routes the packet to the process serving this connection, otherwise a new connection is opened.

    -

    6.2  Clustering Setup

    +

    6.2  Clustering Setup

    Suppose you already configured ejabberd on one machine named (first), and you need to setup another one to make an ejabberd cluster. Then do following steps:

    1. @@ -4268,10 +4314,10 @@ and ‘access’ options because they will be taken from enabled only on one machine in the cluster.

    You can repeat these steps for other machines supposed to serve this domain.

    -

    6.3  Service Load-Balancing

    +

    6.3  Service Load-Balancing

    -

    6.3.1  Components Load-Balancing

    -

    6.3.2  Domain Load-Balancing Algorithm

    +

    6.3.1  Components Load-Balancing

    +

    6.3.2  Domain Load-Balancing Algorithm

    ejabberd includes an algorithm to load balance the components that are plugged on an ejabberd cluster. It means that you can plug one or several instances of the same component on each ejabberd cluster and that the traffic will be automatically distributed.

    The default distribution algorithm try to deliver to a local instance of a component. If several local instances are available, one instance is chosen randomly. If no instance is available locally, one instance is chosen randomly among the remote component instances.

    If you need a different behaviour, you can change the load balancing behaviour with the option domain_balancing. The syntax of the option is the following:

    {domain_balancing, "component.example.com", BalancingCriteria}.

    Several balancing criteria are available:

    • @@ -4280,12 +4326,12 @@ domain.

      -

      6.3.3  Load-Balancing Buckets

      +

      6.3.3  Load-Balancing Buckets

      When there is a risk of failure for a given component, domain balancing can cause service trouble. If one component is failing the service will not work correctly unless the sessions are rebalanced.

      In this case, it is best to limit the problem to the sessions handled by the failing component. This is what the domain_balancing_component_number option does, making the load balancing algorithm not dynamic, but sticky on a fix number of component instances.

      The syntax is:

      {domain_balancing_component_number, "component.example.com", Number}.

      -

      Chapter 7  Debugging

      +

      Chapter 7  Debugging

      -

      7.1  Log Files

      An ejabberd node writes two log files: +

      7.1  Log Files

      An ejabberd node writes two log files:

      ejabberd.log
      is the ejabberd service log, with the messages reported by ejabberd code
      erlang.log
      is the Erlang/OTP system log, with the messages reported by Erlang/OTP using SASL (System Architecture Support Libraries) @@ -4310,12 +4356,12 @@ The ejabberdctl command reopen-log (please refer to section 4.1.1) reopens the log files, and also renames the old ones if you didn’t rename them.

      -

      7.2  Debug Console

      The Debug Console is an Erlang shell attached to an already running ejabberd server. +

      7.2  Debug Console

      The Debug Console is an Erlang shell attached to an already running ejabberd server. With this Erlang shell, an experienced administrator can perform complex tasks.

      This shell gives complete control over the ejabberd server, so it is important to use it with extremely care. There are some simple and safe examples in the article Interconnecting Erlang Nodes

      To exit the shell, close the window or press the keys: control+c control+c.

      -

      7.3  Watchdog Alerts

      +

      7.3  Watchdog Alerts

      ejabberd includes a watchdog mechanism that may be useful to developers when troubleshooting a problem related to memory usage. If a process in the ejabberd server consumes more memory than the configured threshold, @@ -4335,7 +4381,7 @@ or in a conversation with the watchdog alert bot.

      The syntax is: To remove all watchdog admins, set the option with an empty list: 

      {watchdog_admins, []}.

      -

      Appendix A  Internationalization and Localization

      +

      Appendix A  Internationalization and Localization

      The source code of ejabberd supports localization. The translators can edit the gettext .po files @@ -4370,9 +4416,9 @@ HTTP header ‘Accept-Language: ru’

    -

    Appendix B  Release Notes

    +

    Appendix B  Release Notes

    Release notes are available from ejabberd Home Page

    -

    Appendix C  Acknowledgements

    Thanks to all people who contributed to this guide: +

    Appendix C  Acknowledgements

    Thanks to all people who contributed to this guide:

    -

    Appendix D  Copyright Information

    Ejabberd Installation and Operation Guide.
    +

    Appendix D  Copyright Information

    Ejabberd Installation and Operation Guide.
    Copyright © 2003 — 2010 ProcessOne

    This document is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 diff --git a/doc/version.tex b/doc/version.tex index 905ac86f2..255412336 100644 --- a/doc/version.tex +++ b/doc/version.tex @@ -1,2 +1,2 @@ % ejabberd version (automatically generated). -\newcommand{\version}{2.1.x} +\newcommand{\version}{2.1.7}