Žilinská univerzita > Fakulta riadenia a informatiky > Katedra informačných sietí

Configuring IM and presence on Kamailio 3.1 - Howto

This article continue on series of articles about the Kamailio 3.1.x SIP proxy deployed on debian lenny and its features. In previous articles we have:

1) installed clear Kamailio 3.1.x server

2) added Mysql support for persistance location storage

3) SIREMIS web management interface for our kamailio server.

and now, we will configure the IM/presence support.

Prerequsities

To support presence, Kamailio requires special DB tables for presence. So when you installing Mysql support for Kamailio, you have to uncomment in etc/kamailio/kamctlrc file following lines

# If to install tables for the modules in the EXTRA_MODULES variable.
INSTALL_EXTRA_TABLES=ask

# If to install presence related tables.
INSTALL_PRESENCE_TABLES=ask 

and then run

kamdbctl create

If you are further in your configuration and Mysql is already configured, the kamdbctl command has a presence options regarding to adding presence tables.

pstest:/home/palo# kamdbctl database engine 'mysql' loaded
/usr/sbin/kamdbctl $Revision$

usage: kamdbctl create <db name or db_path, optional> .....(creates a new database)
       kamdbctl drop <db name or db_path, optional> .......(!entirely deletes tables!)
       kamdbctl reinit <db name or db_path, optional> .....(!entirely deletes and than re-creates tables!)
       kamdbctl backup <file> .................................(dumps current database to file)
       kamdbctl restore <file> ................................(restores tables from a file)
       kamdbctl copy <new_db> .................................(creates a new db from an existing one)
       kamdbctl migrate <old_db> <new_db> .....................(migrates DB from 1.2 to 1.3, not implemented yet!)
       kamdbctl presence ......................................(adds the presence related tables)
       kamdbctl extra .........................................(adds the extra tables)

So you may run kamdbctl presence, and required tables will be added.

Do not run kamdbctl presence, if you already have installed presence tables using kamdbctl create during initial DB initialisation. Running  kamdbctl presence will do change in kamailio database and it causing problem to run presence correctly. Precisely, the version table of the kamailio database is modyfied such way, that there are added new indexes pointing to a duplicated tables regarding to the presence service with different version indexes.

Dependencies

The following modules must be loaded before this module: 

  • a database module.
  •  sl.
  •  tm.

External Libraries or Applications have to be already installed

  • libxml.
     

Installing the kamailio presence module

apt-get install kamailio-presence-modules

and do not forget restart kamailio server /etc/init.d/kamailio restart

Configuration of the Kamailio for Instant Messaging and Presence (SIMPLE)

The Presence and instant messaging RFC standards are quite complex and wide. For this kind of service over Kamailio we will use presence and xcap modules.

Kamailio 3.1.x

Loading required modules

Open /etc/kamailio/kamailio.cfg and we go through, line by line.

At the top of the cfg file, in define zone blocks, we have prepared

# *** To enable presence server execute:
#     - enable mysql
#     - define WITH_PRESENCE

so we will define presence support

#!define WITH_PRESENCE

and for the basic Presence configuration it is all. All other lines are included inside of the kamailio.cfg as directive blocks.

 

Anyway, we may look through.

In module section (starting with ####### Modules Section ########) we will find

#!ifdef WITH_PRESENCE
loadmodule "presence.so"
loadmodule "presence_xml.so"
#!endif

What mean, that if we have defined presence directive (and we have), the modules will be loaded.

Setting up module parameters

Now we are going to setting module parameters, and in config file we are moving behind

# ----------------- setting module-specific parameters ---------------

so we are in and going through we find prepared lines.

#!ifdef WITH_PRESENCE
# ----- presence params -----
modparam("presence", "db_url", DBURL)

# ----- presence_xml params -----
modparam("presence_xml", "db_url", DBURL)
modparam("presence_xml", "force_active", 1)
#!endif

The first and the second modparam (modparam("presence", "db_url", DBURL), 9modparam("presence_xml", "db_url", DBURL)) is pointing to the database defined in the upper part of the kamailio.cfg. And if we have correctly configured Mysql support, we do not need to deal with.

####### Defined Values #########

# *** Value defines - IDs used later in config
#!ifdef WITH_MYSQL
# - database URL - used to connect to database server by modules such
#       as: auth_db, acc, usrloc, a.s.o.
#!define DBURL "mysql://openser:openserrw@localhost/kamailio"
#!endif

The last modparam (modparam("presence_xml", "force_active", 1)) deals about subscription permissions. The parameters has value 1 if we use XCAP server, otherwise should be 0.

Modifying route logic for using IP/Presence

Inside of the main routing logic, starting woth lines

# Main SIP request routing logic
# - processing of any incoming SIP request starts with this route
route {

we may find preconfigured route calling to handle Presence (route(PRESENCE))

# handle presence related requests
        route(PRESENCE);

where the route(PRESENCE) contain lines

route[PRESENCE] {
        if(!is_method("PUBLISH|SUBSCRIBE"))
                return;

#!ifdef WITH_PRESENCE
        if (!t_newtran())
        {
                sl_reply_error();
                exit;
        };

        if(is_method("PUBLISH"))
        {
                handle_publish();
                t_release();
        }
        else
        if( is_method("SUBSCRIBE"))
        {
                handle_subscribe();
                t_release();
        }
        exit;
#!endif

        # if presence enabled, this part will not be executed
        if (is_method("PUBLISH") || $rU==$null)
        {
                sl_send_reply("404", "Not here");
                exit;
        }
        return;
}

So the default behaviour should be fulfilled and the service should work.

Testing

Using Bria and SipCommuicator with Presence agent settings (not peer to peer) work nice. Transfer of the buddy lists do not work yet.

Using wireshark at both client sides, or ngrep on the server, we should observe message diagram looking something like

PUA                     PA                      WATCHER
                           
  |                       |                      |
  |                       | <----- SUBSCRIBE --- |
  |                       |                      |
  |                       | ------ 200 OK -----> |
  |                       |                      |
  |                       | -----  NOTIFY -----> |
  |                       |                      |
  |                       | <----  200 OK ------ |
  |                       |                      |
  |                       |                      |
  | -------  PUBLISH ---> |                      |
  |                       |                      |
  | <------  200 OK ----  |                      |
  |                       |                      |
  |                       | -----  NOTIFY -----> |
  |                       |                      |
  |                       | <----  200 OK ------ |
  |                       |                      |  

 

Groups: