jabber Module


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. OpenSIPS 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()
2. Contributors
2.1. By Commit Statistics
2.2. By Commit Activity
3. Documentation
3.1. Contributors

List of Tables

2.1. Top contributors by DevScore(1), authored commits(2) and lines added/removed(3)
2.2. Most recently active contributors(1) to this module

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.

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.opensips.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 OpenSIPS, load the dependent modules, set up the routing rules for Jabber gateway.

  • Run OpenSIPS.

The administrator of OpenSIPS/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 OpenSIPS and how local Jabber server is setup.

Next is presented a use case. Prologue:

  • OpenSIPS 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 OpenSIPS server.

*** Routing rules for Jabber gateway First step is to configure OpenSIPS 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 OpenSIPS 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 OpenSIPS 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. OpenSIPS 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 OpenSIPS 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();
...

Chapter 2. Contributors

2.1. By Commit Statistics

Table 2.1. Top contributors by DevScore(1), authored commits(2) and lines added/removed(3)

 NameDevScoreCommitsLines ++Lines --
1. Daniel-Constantin Mierla (@miconda)38180196498172
2. Bogdan-Andrei Iancu (@bogdan-iancu)49281375547
3. Jan Janak (@janakj)32151007498
4. Andrei Pelinescu-Onciul2012101336
5. Razvan Crainea (@razvancrainea)16146538
6. Liviu Chircu (@liviuchircu)11844106
7. Jiri Kuthan (@jiriatipteldotorg)633130
8. Henning Westerholt (@henningw)422923
9. Vlad Patrascu (@rvlad-patrascu)4276
10. Peter Lemenkov (@lemenkov)31327

All remaining contributors: Elena-Ramona Modroiu, Jamey Hicks, Konstantin Bokarius, John Riordan, Vlad Paiu (@vladpaiu), Julián Moreno Patiño, Klaus Darilion, Edson Gellert Schubert.

(1) DevScore = author_commits + author_lines_added / (project_lines_added / project_commits) + author_lines_deleted / (project_lines_deleted / project_commits)

(2) including any documentation-related commits, excluding merge commits. Regarding imported patches/code, we do our best to count the work on behalf of the proper owner, as per the "fix_authors" and "mod_renames" arrays in opensips/doc/build-contrib.sh. If you identify any patches/commits which do not get properly attributed to you, please submit a pull request which extends "fix_authors" and/or "mod_renames".

(3) ignoring whitespace edits, renamed files and auto-generated files

2.2. By Commit Activity

Table 2.2. Most recently active contributors(1) to this module

 NameCommit Activity
1. Liviu Chircu (@liviuchircu)Mar 2014 - Jun 2018
2. Razvan Crainea (@razvancrainea)Aug 2015 - Jan 2018
3. Vlad Patrascu (@rvlad-patrascu)May 2017 - Jul 2017
4. Bogdan-Andrei Iancu (@bogdan-iancu)Jun 2002 - Sep 2016
5. Julián Moreno PatiñoFeb 2016 - Feb 2016
6. Vlad Paiu (@vladpaiu)Feb 2012 - Feb 2012
7. John RiordanMay 2009 - May 2009
8. Klaus DarilionJul 2008 - Jul 2008
9. Henning Westerholt (@henningw)Jan 2008 - Jun 2008
10. Daniel-Constantin Mierla (@miconda)Jul 2002 - Mar 2008

All remaining contributors: Konstantin Bokarius, Edson Gellert Schubert, Peter Lemenkov (@lemenkov), Elena-Ramona Modroiu, Jan Janak (@janakj), Andrei Pelinescu-Onciul, Jamey Hicks, Jiri Kuthan (@jiriatipteldotorg).

(1) including any documentation-related commits, excluding merge commits

Chapter 3. Documentation

3.1. Contributors

Last edited by: Liviu Chircu (@liviuchircu), Vlad Patrascu (@rvlad-patrascu), Bogdan-Andrei Iancu (@bogdan-iancu), Klaus Darilion, Daniel-Constantin Mierla (@miconda), Konstantin Bokarius, Edson Gellert Schubert, Peter Lemenkov (@lemenkov), Elena-Ramona Modroiu, Jan Janak (@janakj).

Documentation Copyrights:

Copyright © 2003 FhG FOKUS