kamailio/obsolete/jabber_k

jabber Module

Daniel-Constantin Mierla

   <miconda@gmail.com>

Edited by

Daniel-Constantin Mierla

   <miconda@gmail.com>

   Copyright © 2003 FhG FOKUS
   Revision History
   Revision $Revision$ $Date: 2008-08-06 12:08:33 +0200
                              (Mi, 06 Aug 2008) $
     __________________________________________________________

   Table of Contents

   1. Admin Guide

        1.1. Overview

              1.1.1. New Features

        1.2. Admin's Guide
        1.3. Admin Guide
        1.4. Dependencies

              1.4.1. Kamailio Modules
              1.4.2. External Libraries or Applications

        1.5. Exported Parameters

              1.5.1. db_url (string)
              1.5.2. jaddress (string)
              1.5.3. jport (integer)
              1.5.4. jdomain (string)
              1.5.5. aliases (string)
              1.5.6. proxy (string)
              1.5.7. registrar (string)
              1.5.8. workers (integer)
              1.5.9. max_jobs (integer)
              1.5.10. cache_time (integer)
              1.5.11. delay_time (integer)
              1.5.12. sleep_time (integer)
              1.5.13. check_time (integer)
              1.5.14. priority (str)

        1.6. Exported Functions

              1.6.1. jab_send_message()
              1.6.2. jab_join_jconf()
              1.6.3. jab_exit_jconf()
              1.6.4. jab_go_online()
              1.6.5. jab_go_offline()

   List of Examples

   1.1. Set db_url parameter
   1.2. Set jaddress parameter
   1.3. Set jport parameter
   1.4. Set jdomain parameter
   1.5. Set jdomain parameter
   1.6. Set proxy parameter
   1.7. Set registrar parameter
   1.8. Set workers parameter
   1.9. Set max_jobs parameter
   1.10. Set cache_time parameter
   1.11. Set delay_time parameter
   1.12. Set sleep_time parameter
   1.13. Set check_time parameter
   1.14. Set priority parameter
   1.15. jab_send_message() usage
   1.16. jab_join_jconf() usage
   1.17. jab_exit_jconf() usage
   1.18. jab_go_online() usage
   1.19. jab_go_offline() usage

Chapter 1. Admin Guide

1.1. Overview

   This is new version of Jabber module that integrates XODE XML
   parser for parsing Jabber messages. That introduces a new
   module dependency: expat library.

   Expat is a common XML library and is the fastest available for
   Linux/Unix, the second over all, after msxml library. It is
   integrated in most of well known Linux distributions.

   Please not that this module is deprecated and will be removed
   in the next major release of Kamailio. The purple module should
   be used instead.

1.1.1. New Features

     * Presence support (see doc/xxjab.cfg for a sample cfg file)
       (January 2003).
     * SIP to Jabber conference support (December 2003).
     * Possibility to manage all kinds of Jabber messages
       (message/presence/iq) (December 2003).
     * Aliases -- Possibility to set host aliases for addresses
       (see parameter's desc.) (December 2003).
     * Send received SIP MESSAGE messages to different IM networks
       (Jabber, ICQ,MSN, AIM, Yahoo) using a Jabber server
       (December 2003).
     * Send incoming Jabber instant messages as SIP MESSAGE
       messages.
     * Gateways detection -- Ability to see whether an IM gateway
       is up or down.

1.2. Admin's Guide

Note

   A more complete guide about SIMPLE2Jabber gateway can be found
   at http://www.kamailio.org/. The part below will be removed
   soon, only the manual from web will be updated.

   The Jabber server setup is not a subject of this guide. Check
   http://www.jabber.org for that.

   Useful scripts, for creating Jabber Gateway database, or for
   managing the Jabber accounts form web are located in 'doc'
   subdirectory of the module.

   Main steps of using the Jabber gateway:
     * Create the MySQL database.
     * Setup the local Jabber server.
     * Set the module parameter values in cfg file of Kamailio,
       load the dependent modules, set up the routing rules for
       Jabber gateway.
     * Run Kamailio.

   The administrator of Kamailio/Jabber gateway must inform the
   users what are the aliases for Jabber/Other IM networks. Other
   IMs could be AIM, ICQ, MSN, Yahoo, and so on.

   These aliases depend on the server hostname where runs Kamailio
   and how local Jabber server is setup.

   Next is presented a use case. Prologue:
     * Kamailio is running on "server.org".
     * Local Jabber server is running on "jabsrv.server.org".
     * Jabber network alias (first part of "jdomain") is
       "jabber.server.org"

   The aliases for other IM networks must be the same as JID set
   in Jabber configuration file for each IM transport.

   The JIDs of Jabber transports must start with the name of the
   network. For AIM, JID must start with "aim.", for ICQ with
   "icq" (that because I use icqv7-t), for MSN with "msn." and for
   Yahoo with "yahoo.". The gateway needs these to find out what
   transport is working and which not. For our use case these
   could be like "aim.server.org", "icq.server.org",
   "msn.server.org", "yahoo.server.org".

   It is indicated to have these aliases in DNS, thus the client
   application can resolve the DNS name. Otherwise there must be
   set the outbound proxy to Kamailio server.

   *** Routing rules for Jabber gateway First step is to configure
   Kamailio to recognize messages for Jabber gateway. Look at
   "doc/xjab.cfg" to see a sample. The idea is to look in messages
   for destination address and if it contains Jabber alias or
   other IM alias, that means the message is for Jabber gateway.

   Next step is to find out what means that message for Jabber
   gateway. It could be a special message what triggers the
   gateway to take an action or is a simple message which should
   be delivered to Jabber network (using the method
   "jab_send_message").

   The special messages are for:
     * Registering to Jabber server (go online in Jabber
       network)--here must be called "jab_go_online" method.
     * Leaving the Jabber network (go offline in Jabber
       network)--here must be called "jab_go_offline" method.
     * Joining a Jabber conference room--here must be called
       "jab_join_jconf".
     * Leaving a Jabber conference room--here must be called
       "jab_exit_jconf".

   The destination address must follow the following patterns:
     * For Jabber network:
       "username<delim>jabber_server@jabber_alias".
     * For Jabber conference:
       "nickname<delim>room<delim>conference_server@jabber_alias".
     * For AIM network: "aim_username@aim_alias".
     * For ICQ network: "icq_number@icq_alias".
     * For MSN network: "msn_username<delim>msn_server@msn_alias".
       msn_server can be "msn.com" or "hotmail.com".
     * For YAHOO network: "yahoo_username@yahoo_alias".

Note

   "jabber_alias" is the first part of "jdomain".

1.3. Admin Guide

   The user must activate his Jabber account associated with his
   SIP id. For each other IM network on which he wants to send
   messages, he must set an account for that IM network. The
   gateway is not able to create new account in foreign networks,
   excepting local Jabber server.

   When you want to send a message to someone in other IM network,
   you must set the destination of the message according with the
   pattern corresponding to that IM network (see last part of
   "Admin guide" chapter).

   Sending a message to user@jabber.xxx.org which is in Jabber
   network, the destination must be:
   user<delim>jabber.xxx.org@jabber_alias.

   For someone who is in Yahoo network the destination must be:
   user@yahoo_alias

Note

   The Kamailio administrator have to set the Jabber transports
   for each IM network in order to be able to send messages to
   those networks. The alias of each IM network can be found out
   from Kamailio admin.

   You cannot send messages from your SIP client to your
   associated Jabber account--is something like sending messages
   to yourself.

1.4. Dependencies

1.4.1. Kamailio Modules

   The following modules must be loaded before this module:
     * A database module.
     * pa (Optionally) - Presence Agent.
     * tm - Transaction Manager.

1.4.2. External Libraries or Applications

   The following libraries or applications must be installed
   before running Kamailio with this module loaded:
     * Expat library.

1.5. Exported Parameters

1.5.1. db_url (string)

   SQL URL of database.

   Default value is "mysql://root@127.0.0.1/sip_jab".

   Example 1.1. Set db_url parameter
...
modparam("jabber", "db_url", "mysql://username:password@host/sip_jab")
...

1.5.2. jaddress (string)

   IP or hostname of Jabber server -- it must be the same as the
   value from <host> tag of Jabber server config file.

   Default value is "127.0.0.1".

   Example 1.2. Set jaddress parameter
...
modparam("jabber", "jaddress", "1.2.3.4")
...

1.5.3. jport (integer)

   Port number of Jabber server.

   Default value is "5222".

   Example 1.3. Set jport parameter
...
modparam("jabber", "jport", 1234)
...

1.5.4. jdomain (string)

   Format: jabber.sipserver.com=<delim>. If the destination is for
   Jabber network the URI should be like:
   username<delim>jabber_server@jdomain or
   nickname<delim>roomname<delim>conference_server@jdomain

   <delim> must be a un-reserved character. By default this
   character is * . The destination will be transformed to
   username@jabber_server or roomname@conference_server/nickname
   before the message is sent to Jabber server.

   Default value is none.

   Example 1.4. Set jdomain parameter
...
modparam("jabber", "jdomain", "jabber.sipserver.com=*")
...

1.5.5. aliases (string)

   Aliases for IM networks.

   Format: "N;alias1=<delim1>;...;aliasN=<delimN>;" Destinations
   like '*@aliasX' could have other format than those specified
   for Jabber network. All <delim> from user part of the
   destination address will be changed to <delimX> if the
   destination address contains <aliasX>.

   (Ex: jdomain is 'jabber.x.com=*' and msn_alias is
   'msn.x.com=%'. The destination address forM MSN Network, on SIP
   side, is like 'username*hotmail.com@msn.x.com'. The destination
   address will be transformed to
   'username%hotmail.com@msn.x.com'. 'msn.x.com' must be the same
   as the JID associated with MSN transport in Jabber
   configuration file (usually is 'jabberd.xml'))

   Default value is none.

   Example 1.5. Set jdomain parameter
...
modparam("jabber", "aliases", "1;msn.x.com=%")
...

1.5.6. proxy (string)

   Outbound proxy address.

   Format: ip_address:port hostname:port

   All SIP messages generated by gateway will be sent to that
   address. If is missing, the message will be delivered to the
   hostname of the destination address

   Default value is none.

   Example 1.6. Set proxy parameter
...
modparam("jabber", "proxy", "10.0.0.1:5060 sipserver.com:5060")
...

1.5.7. registrar (string)

   The address in whose behalf the INFO and ERROR messages are
   sent.

   Default value is "jabber_gateway@127.0.0.1".

   Example 1.7. Set registrar parameter
...
modparam("jabber", "registrar", "jabber_gateway@127.0.0.1")
...

1.5.8. workers (integer)

   Number of workers.

   Default value is 2.

   Example 1.8. Set workers parameter
...
modparam("jabber", "workers", 2)
...

1.5.9. max_jobs (integer)

   Maximum jobs per worker.

   Default value is 10.

   Example 1.9. Set max_jobs parameter
...
modparam("jabber", "max_jobs", 10)
...

1.5.10. cache_time (integer)

   Cache time of a Jabber connection.

   Default value is 600.

   Example 1.10. Set cache_time parameter
...
modparam("jabber", "cache_time", 600)
...

1.5.11. delay_time (integer)

   Time to keep a SIP message (in seconds).

   Default value is 90 seconds.

   Example 1.11. Set delay_time parameter
...
modparam("jabber", "delay_time", 90)
...

1.5.12. sleep_time (integer)

   Time between expired Jabber connections checking (in seconds).

   Default value is 20 seconds.

   Example 1.12. Set sleep_time parameter
...
modparam("jabber", "sleep_time", 20)
...

1.5.13. check_time (integer)

   Time between checking the status of JabberGW workers (in
   seconds).

   Default value is 20 seconds.

   Example 1.13. Set check_time parameter
...
modparam("jabber", "check_time", 20)
...

1.5.14. priority (str)

   Presence priority for Jabber gateway.

   Default value is "9".

   Example 1.14. Set priority parameter
...
modparam("jabber", "priority", "3")
...

1.6. Exported Functions

1.6.1.  jab_send_message()

   Converts SIP MESSAGE message to a Jabber message and sends it
   to Jabber server.

   This function can be used from REQUEST_ROUTE.

   Example 1.15. jab_send_message() usage
...
jab_send_message();
...

1.6.2.  jab_join_jconf()

   Join a Jabber conference--the nickname, room name and
   conference server address should be included in To header as:
   nickname%roomname%conference_server@jdomain . If the nickname
   is missing, then the SIP username is used.

   This function can be used from REQUEST_ROUTE.

   Example 1.16. jab_join_jconf() usage
...
jab_join_jconf();
...

1.6.3.  jab_exit_jconf()

   Leave a Jabber conference--the nickname, room name and
   conference server address should be included in To header as:
   nickname%roomname%conference_server@jdomain .

   This function can be used from REQUEST_ROUTE.

   Example 1.17. jab_exit_jconf() usage
...
jab_exit_jconf();
...

1.6.4.  jab_go_online()

   Register to the Jabber server with associated Jabber ID of the
   SIP user.

   This function can be used from REQUEST_ROUTE.

   Example 1.18. jab_go_online() usage
...
jab_go_online();
...

1.6.5.  jab_go_offline()

   Log off from Jabber server the associated Jabber ID of the SIP
   user.

   This function can be used from REQUEST_ROUTE.

   Example 1.19. jab_go_offline() usage
...
jab_go_offline();
...