From b84f85ba8a1e95b42029520a1a4f4b4b28e3c998 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micka=C3=ABl=20R=C3=A9mond?= Date: Sat, 1 Dec 2007 16:43:04 +0000 Subject: * doc/Makefile: echo seems to interpret \n and \v under MacOSX Leopard. I fixed the problem but let me know if it breaks build chain in other contexts. SVN Revision: 1011 --- doc/dev.html | 533 +++++++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 354 insertions(+), 179 deletions(-) (limited to 'doc/dev.html') diff --git a/doc/dev.html b/doc/dev.html index e705c7047..6330339a5 100644 --- a/doc/dev.html +++ b/doc/dev.html @@ -1,23 +1,15 @@ + -Ejabberd 2.0.0 beta Developers Guide - - - +Ejabberd 2.0.0b1 Developers Guide + + + + - -

+ + + + + -

-

Ejabberd 2.0.0 beta Developers Guide

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

+
+
+ -logo.png + + +
+

Ejabberd 2.0.0b1 Developers Guide

+

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


+
+
+ + logo.png + +
+
-
I can thoroughly recommend ejabberd for ease of setup – -Kevin Smith, Current maintainer of the Psi project
-

Contents

+
I can thoroughly recommend ejabberd for ease of setup – + Kevin Smith, Current maintainer of the Psi project
+ + +

Contents

+ + +
  • 4  Authentication +

    Introduction -

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

    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.

    -

    1  Key Features

    +4.0.1  External + + +

  • 5  XML Representation +
  • 6  Module xml +
  • 7  Module xml_stream +
  • 8  Modules + + + +Introduction +
    +
    +
    +
    +ejabberd is a free and open source instant messaging server written in Erlang.
    +
    +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.
    +
    + + +

    1  Key Features

    + -

    ejabberd is: -


    +
    +
  • Open Standards: ejabberd is the first Open Source Jabber server claiming to fully comply to the XMPP standard.
    • -

    2  Additional Features

    +

  • XML-based protocol. +
  • Many protocols supported. + + + +

    2  Additional Features

    + -

    Moreover, ejabberd comes with a wide range of other state-of-the-art features: -

    +
  • Databases -
  • Authentication +
  • Native PostgreSQL support. +
  • Mnesia. +
  • ODBC data storage support. +
  • Microsoft SQL Server support. +
  • Authentication -
  • Others +LDAP and ODBC.
  • External Authentication script. +
  • Internal Authentication. + +
  • Others -
    • -

    3  How it Works

    -

    A Jabber domain is served by one or more ejabberd nodes. These nodes can +

  • Interface with networks such as AIM, ICQ and MSN. +
  • Statistics via Statistics Gathering (XEP-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. + + + + + +

    3  How it Works

    + + +A Jabber domain is served by one or more ejabberd nodes. These nodes can be run on different machines that are connected via a network. They all must have the ability to connect to port 4369 of all another nodes, and must have the same magic cookie (see Erlang/OTP documentation, in other words the file ~ejabberd/.erlang.cookie must be the same on all nodes). This is needed because all nodes exchange information about connected users, S2S -connections, registered services, etc…

    Each ejabberd node have following modules: -

    + + +

    3.1  Router

    + +This module is the main router of Jabber packets on each node. It routes them based on their destinations domains. It has two tables: local and global routes. First, domain of packet destination searched in local table, and if it found, then the packet is routed to appropriate process. If no, then it searches in global table, and is routed to the appropriate ejabberd node or process. If it does not exists in either tables, then it sent to the S2S -manager.

    -

    3.2  Local Router

    This module routes packets which have a destination domain equal to this server +manager.
    +
    + + +

    3.2  Local Router

    + +This module routes packets which have a destination domain equal to this server 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 +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 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 Jabber servers. First, it checks if an +the packet is sent to session manager on that node.
    +
    + + +

    3.4  S2S Manager

    + +This module routes packets to other Jabber servers. First, it checks if an open S2S connection from the domain of the packet source to the domain of packet destination already exists. If it is open on another node, then it routes the packet to S2S manager on that node, if it is open on this node, then it is routed to the process that serves this connection, and if a connection -does not exist, then it is opened and registered.

    -

    4  XML Representation

    -

    Each XML stanza is represented as the following tuple: -

    XMLElement = {xmlelement, Name, Attrs, [ElementOrCDATA]}
+does not exist, then it is opened and registered.
    
+
    
+
+
+
    4  Authentication
    
+
+
+
+
    4.0.1  External
    
+
+
+
+The external authentication script follows
+the erlang port driver API.
    
+
    
+That script is supposed to do theses actions, in an infinite loop:
+
    • 
+read from stdin: AABBBBBBBBB.....
+ 
      • 
+ A: 2 bytes of length data (a short in network byte order)
+ 
      • B: a string of length found in A that contains operation in plain text
+ operation are as follows:
+ 
        • 
+ auth:User:Server:Password (check if a username/password pair is correct)
+ 
        • isuser:User:Server (check if it's a valid user)
+ 
        • setpass:User:Server:Password (set user's password)
+ 
        
+ 
      
+
    • write to stdout: AABB
+ 
      • 
+ A: the number 2 (coded as a short, which is bytes length of following result)
+ 
      • B: the result code (coded as a short), should be 1 for success/valid, or 0 for failure/invalid
+ 
      
+
    
+Example python script
+
    +#!/usr/bin/python
+
+import sys
+from struct import *
+
+def from_ejabberd():
+    input_length = sys.stdin.read(2)
+    (size,) = unpack('>h', input_length)
+    return sys.stdin.read(size).split(':')
+
+def to_ejabberd(bool):
+    answer = 0
+    if bool:
+        answer = 1
+    token = pack('>hh', 2, answer)
+    sys.stdout.write(token)
+    sys.stdout.flush()
+
+def auth(username, server, password):
+    return True
+
+def isuser(username, server):
+    return True
+
+def setpass(username, server, password):
+    return True
+
+while True:
+    data = from_ejabberd()
+    success = False
+    if data[0] == "auth":
+        success = auth(data[1], data[2], data[3])
+    elif data[0] == "isuser":
+        success = isuser(data[1], data[2])
+    elif data[0] == "setpass":
+        success = setpass(data[1], data[2], data[3])
+    to_ejabberd(success)
+
    
+
+
+
    5  XML Representation
    
+
+
+Each XML stanza is represented as the following tuple:
+
    +XMLElement = {xmlelement, Name, Attrs, [ElementOrCDATA]}
         Name = string()
         Attrs = [Attr]
         Attr = {Key, Val}
@@ -183,30 +320,45 @@ does not exist, then it is opened and registered.
    
-
    5  Module xml
    
-
    
-
    element_to_string(El) -> string()
-
    El = XMLElement
-
    Returns string representation of XML stanza El.
    crypt(S) -> string()
-
    S = string()
+
    
+
+
+
    6  Module xml
    
+
+
+
    element_to_string(El) -> string()
+
    +El = XMLElement
+
    Returns string representation of XML stanza El.
    
+
    
+
    crypt(S) -> string()
+
    +S = string()
 
    Returns string which correspond to S with encoded XML special
-characters.
    remove_cdata(ECList) -> EList
-
    ECList = [ElementOrCDATA]
+ characters.
    
+
    
+
    remove_cdata(ECList) -> EList
+
    +ECList = [ElementOrCDATA]
 EList = [XMLElement]
-
    EList is a list of all non-CDATA elements of ECList.
    get_path_s(El, Path) -> Res
-
    El = XMLElement
+
    EList is a list of all non-CDATA elements of ECList.
    
+
    
+
    get_path_s(El, Path) -> Res
+
    +El = XMLElement
 Path = [PathItem]
 PathItem = PathElem | PathAttr | PathCDATA
 PathElem = {elem, Name}
@@ -215,56 +367,74 @@ PathCDATA = cdata
 Name = string()
 Res = string() | XMLElement
 
    If Path is empty, then returns El. Else sequentially
-consider elements of Path. Each element is one of:
-
    
-
    {elem, Name} Name is name of subelement of
-El, if such element exists, then this element considered in
-following steps, else returns empty string.
-
    {attr, Name} If El have attribute Name, then
-returns value of this attribute, else returns empty string.
-
    cdata Returns CDATA of El.
-
    TODO:
-
             get_cdata/1, get_tag_cdata/1
+ consider elements of Path. Each element is one of:
+ 
    {elem, Name} Name is name of subelement of
+ El, if such element exists, then this element considered in
+ following steps, else returns empty string.
+ 
    {attr, Name} If El have attribute Name, then
+ returns value of this attribute, else returns empty string.
+ 
    cdata Returns CDATA of El.
+ 

    
+
    
+
    TODO:
+
    +         get_cdata/1, get_tag_cdata/1
          get_attr/2, get_attr_s/2
          get_tag_attr/2, get_tag_attr_s/2
          get_subtag/2
-
    
-
    6  Module xml_stream
    
-
    
-
    parse_element(Str) -> XMLElement | {error, Err}
-
    Str = string()
+
    
+
+
+
    7  Module xml_stream
    
+
+
+
    parse_element(Str) -> XMLElement | {error, Err}
+
    +Str = string()
 Err = term()
 
    Parses Str using XML parser, returns either parsed element or error
-tuple.
-
    
-
    7  Modules
    
-
    
-
    7.1  Module gen_iq_handler
    
-
    The module gen_iq_handler allows to easily write handlers for IQ packets
-of particular XML namespaces that addressed to server or to users bare JIDs.
    In this module the following functions are defined:
-
    
-
    add_iq_handler(Component, Host, NS, Module, Function, Type)
-
    Component = Module = Function = atom()
+ tuple.
+
    
+
+
+
    8  Modules
    
+
+
+
+
+
    8.1  Module gen_iq_handler
    
+
+
+The module gen_iq_handler allows to easily write handlers for IQ packets
+of particular XML namespaces that addressed to server or to users bare JIDs.
    
+
    
+In this module the following functions are defined:
+
    add_iq_handler(Component, Host, NS, Module, Function, Type)
+
    +Component = Module = Function = atom()
 Host = NS = string()
 Type = no_queue | one_queue | parallel
 
    Registers function Module:Function as handler for IQ packets on
-virtual host Host that contain child of namespace NS in
-Component. Queueing discipline is Type. There are at least
-two components defined:
-
    
-
    ejabberd_local Handles packets that addressed to server JID;
-
    ejabberd_sm Handles packets that addressed to users bare JIDs.
-
    
-
    remove_iq_handler(Component, Host, NS)
-
    Component = atom()
+ virtual host Host that contain child of namespace NS in
+ Component. Queueing discipline is Type. There are at least
+ two components defined:
+ 
    ejabberd_local Handles packets that addressed to server JID;
+ 
    ejabberd_sm Handles packets that addressed to users bare JIDs.
+ 
    
+
    remove_iq_handler(Component, Host, NS)
+
    +Component = atom()
 Host = NS = string()
 
    Removes IQ handler on virtual host Host for namespace NS from
-Component.
-
    Handler function must have the following type:
-
    
-
    Module:Function(From, To, IQ)
-
    From = To = jid()
-
    -module(mod_cputime).
+ Component.
+
    
+Handler function must have the following type:
+
    Module:Function(From, To, IQ)
+
    +From = To = jid()
+
    
+
    +-module(mod_cputime).
 
 -behaviour(gen_mod).
 
@@ -298,9 +468,14 @@ process_local_iq(From, To, {iq, ID, Type, XMLNS, SubEl}) ->
                [{"xmlns", ?NS_CPUTIME}],
                [{xmlelement, "cputime", [], [{xmlcdata, SCPUTime}]}]}]}
     end.
-
    
-
    7.2  Services
    
-
    -module(mod_echo).
+
    
+
+
+
    8.2  Services
    
+
+
+
    +-module(mod_echo).
 
 -behaviour(gen_mod).
 
@@ -334,10 +509,10 @@ stop(Host) ->
     Proc = gen_mod:get_module_proc(Host, ?PROCNAME),
     Proc ! stop,
     {wait, Proc}.
-
    
+
    
 
 
 
 
    This document was translated from LATEX by
-HEVEA.
    
+HEVEA.
 
-- 
cgit v1.2.3