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

Installing base Kamailio IMS platform on the debian squeeze - 32bit

This install guide is based on the official install guide from http://www.ng-voice.com/our-solution/installation/

This guide describes the base component installation only. The platform is using four virtual machines, one for each IMS component (PCSCF, SCSCF, ICSCF, HSS).

Deployment OS is debian squeeze, 32 bit (because only 32 bit packages are available, 64bit have to be compiled). 

Preparation

Prepare DNS records:

$ORIGIN test1.local.
@               NAPTR 10 100 "S" "SIP+D2U" "" _sip._udp.pcscf.test1.local.
@               NAPTR 20 100 "S" "SIP+D2T" "" _sip._tcp.pcscf.test1.local.
pcscf           IN      A       158.193.139.40
_sip.pcscf      IN      SRV 0 0 5060 pcscf
_sip._udp.pcscf IN      SRV 0 0 5060 pcscf
_sip._tcp.pcscf IN      SRV 0 0 5060 pcscf
icscf           IN      A       158.193.139.41
_sip            IN      SRV 0 0 5060 icscf
_sip._udp       IN      SRV 0 0 5060 icscf
_sip._tcp       IN      SRV 0 0 5060 icscf
scscf           IN      A       158.193.139.42
_sip.scscf      IN      SRV 0 0 5060 scscf
_sip._udp.scscf IN      SRV 0 0 5060 scscf
_sip._tcp.scscf IN      SRV 0 0 5060 scscf
hss             IN      A       158.193.139.43
presence        IN      CNAME   hss

Prepare repositories

Install the Key for this repository:

wget http://repository.ng-voice.com/ngvoice-debian-gpg.key
apt-key add ngvoice-debian-gpg.key

Then add the repository to your “/etc/apt/sources.list”:

deb http://repository.ng-voice.com lenny main contrib non-free
deb-src http://repository.ng-voice.com lenny main contrib non-free
and update the repository:
apt-get update

Installing

For all CSCF components install the kamailio and the ims module packages

apt-get install kamailio kamailio-ims-modules

Open the  /etc/default/kamailio file:

# Set to yes to enable kamailio, once configured properly.
RUN_KAMAILIO=yes

# User to run as
USER=kamailio

# Group to run as
GROUP=kamailio

# Amount of memory to allocate for the running Kamailio server (in Mb)
MEMORY=64

Installing P-CSCF

from the guide "Copy the required config to kamailio.cfg (e.g. pcscf.cfg)", but I'll backup the old kamailio file and make symlink

cd /etc/kamailio
mv kamailio.cfg kamailio.cfg.dist
ln -s pcscf.cfg kamailio.cfg

 

Installing S-CSCF

 the same for P-CSCSF

cd /etc/kamailio
mv kamailio.cfg kamailio.cfg.dist
ln -s scscf.cfg kamailio.cfg

 now

change “ng-voice.com” and the IP to your domain/IP, please remember also the escaped versions of the domain and the IP, e.g. “pcscf\.ng-voice\.com). For components with Diameter-Interface (e.g. I-/S-CSCF) you will need to modify the according XML-files, e.g. “pcscf.xml”

 

so we will do it for our cscf entities. Nice trick from of our linux admin, open required cfg file inside of the vim editor, then press doubledot":" and put following command %s/ng-voice.com/test1.local/g to rewrite all ng-voice.com strings to our domain test1.local. Becasue pcscf has 10 lines with ng-voice, scscf has 17 line with ng-voice.com domain.

Then change the IP addresses inside of the cfg file for the pcscf from 109.239.50.67 to yours, in our case 158.193.139.40 and for scscf 192.168.10.2: to 158.193.139.42. They were hardcoded inside of cfg files for pcscf and scscf.

 

Edit the kamailio diameter module configuration file /etc/kamailio/scscf.xml:

  • change the IMS domain name in whole conf. file (i.e. from open-ims.test to test1.local)
  • edit IP address in bind parameter of Acceptor tag. This step is essential in case of using HSS on separate server. Acceptor port is port that will listen for incoming connections from HSS server. This Acceptor tag must be paired with Peer tag from /etc/fhoss/DiameterPeerHSS.xml file on HSS server:

Acceptor from /etc/kamailio/scscf.xml:

<Acceptor port="3870" bind="158.193.139.42"/>

Peer tag from /etc/fhoss/DiameterPeerHSS.xml (on HSS server):

<Peer FQDN="scscf.test1.local" Realm="test1.local" port="3870" />

In this example, the IP address 158.193.139.42 is IP address of scscf.test1.local. And both port parameters must have the same value (3870 in our case).

 

Edit the Kamailio init script configuration file /etc/default/kamailio and make sure you have configured the following parameters:

# Set to yes to enable kamailio, once configured properly.
RUN_KAMAILIO=yes

# User to run as
USER=kamailio

# Group to run as
GROUP=kamailio

and we may start a ims S-CSCF component service, which is running default configuration

/etc/init.d/kamailio start

 

Installing I-CSCF

 

MySQL Database installation

MySQL database is required by i-scscf module. During installation you will be asked for mysql root password, which will be needed in some next steps:

apt-get install mysql-server

And continue with database configruation:

# login to database with admin credentials (you will be asked for mysql root password)
mysql -uroot -p
# create database used by icscf kamailio module
mysql> create database icscf;
# create database user with restricted privileges
mysql> CREATE USER 'icscf'@'localhost' IDENTIFIED BY 'secret';
# grant privileges for that user only to icscf database
mysql> GRANT ALL PRIVILEGES ON icscf.* TO 'icscf'@'localhost';

After configuration of mysql database, we need to build its DB structure:

  • download following structure icscf.sql file from this location using wget:
wget http://mobicents.googlecode.com/svn/trunk/servers/sip-servlets/sip-servlets-examples\
/diameter-openims/conf/open-ims/database/icscf.sql
  • modify that file for adaptation with your topology configuration and domain name definitions!
    • in this file is located information for I-CSCF about available S-CSCF servers. Only S-CSCF servers defined in this SQL database table (table s_cscfs) will be contacted by I-CSCF when processing SIP requests messages from P-CSCF! So change the default S-CSCF domain name value and port to someting that you've used in your topology! Default is: 
      sip:scscf.open-ims.test:6060
    • change domain name open-ims.test (two occurences in that file) to something that you are using (in our case: test1.local)
  • import that file to mysql with following command:
mysql -uroot -p icscf < icscf.sql

Kamailio installation

Before installation of kamailio packages, we need to download special package libmysqlclient15off which is required by  kamailio-mysql-modules package (distribution repository provides this package only in newest version):

  • open web browser and navigate to http://packages.debian.org/lenny/i386/libmysqlclient15off/download
  • copy deb package link address from one of the offered link locations
  • use that link to get the .deb file directly to i-cscf linux machine using wget: wget <link>
  • install that libmysqlclient15off*.deb file: dpkg -i libmysqlclient15off*.deb and proceed with following step:
apt-get install kamailio kamailio-ims-modules kamailio-mysql-modules

From the guide "Copy the required config to kamailio.cfg (e.g. pcscf.cfg)", but I'll backup the old kamailio file and make symlink:

cd /etc/kamailio
mv kamailio.cfg kamailio.cfg.dist
ln -s icscf.cfg kamailio.cfg

Edit /etc/kamailio/kamailio.cfg configuration file:

  • change the #!define DBURL at the beginning of configuration file accordingly. In our case:
#!define DBURL "mysql://icscf:secret@localhost/icscf"
  • change the order of the following loadmodule directives to avoid kamailio startup errors to form like this:
loadmodule "tm.so"
modparam("tm", "fr_timer", 10000)

loadmodule "sl.so"

This will prevent generating following kamailio errors:

ERROR: tm [tm_load.c:47]: tm:load_tm: Module not initialized yet, make sure
that all modules that need tm module are loaded after tm in the
configuration file
INFO: sl [sl.c:186]: could not bind tm module - only stateless mode available
  • In whole configuration file, change the IMS domain name from default open-ims.test to another one used in your IMS platform. Be careful with automatic string replacement function, because in routing part of config file there is domain name escaped with special character in this form: open-ims\.test

Edit the kamailio diameter module configuration file /etc/kamailio/icscf.xml:

  • change the IMS domain name in whole conf. file (i.e. from open-ims.test to test1.local)
  • edit IP address in bind parameter of Acceptor tag. This step is essential in case of using HSS on separate server. Acceptor port is port that will listen for incoming connections from HSS server. This Acceptor tag must be paired with Peer tag from /etc/fhoss/DiameterPeerHSS.xml file on HSS server:

Acceptor from /etc/kamailio/icscf.xml:

<Acceptor port="3869" bind="158.193.139.41"/>

Peer tag from /etc/fhoss/DiameterPeerHSS.xml (on HSS server):

<Peer FQDN="icscf.test1.local" Realm="test1.local" port="3869" />

In this example, the IP address 158.193.139.41 is IP address of icscf.test1.local. And both port parameters must have the same value (3869 in our case).

 

Edit the Kamailio init script configuration file /etc/default/kamailio and make sure you have configured the following parameters:

# Set to yes to enable kamailio, once configured properly.
RUN_KAMAILIO=yes

# User to run as
USER=kamailio

# Group to run as
GROUP=kamailio

Start I-SCSF kamailio instance:

/etc/init.d/kamailio start

 

Installation of the HSS

Kamailio IMS environment uses as role of HSS server implementation of OpenIMSCore HSS created by Fraunhofer Institute for Open Communication Systems with name FHoSS (The FOKUS Home Subscriber Server). This implementation is available in package form through the classic debian repository, but needs java, that is located in non-free part of debian repository.

To get the package successfully installed, we need to modify repository information file /etc/apt/sources.list and append non-free repository at the end of next two lines:

deb http://ftp.antik.sk/debian/ squeeze main non-free
deb-src http://ftp.antik.sk/debian/ squeeze main non-free

If you forget previous step, you'll see following complaint message:

The following packages have unmet dependencies:
 openimscore-fhoss : Depends: sun-java6-jre but it is not installable

This HSS implementation uses as its backend MySQL database, so we need install mysql server also on this host. This step of installing mysql server you need to accomplish before installation of HSS, because HSS package executes post-installation scripts that creates HSS database with tables and users and this step needs functional and running mysql server.

During mysql installation you will be asked for mysql root password, which will be needed in some next steps:

apt-get install mysql-server

HSS installation:

the HSS package is named openimscore-fhoss, for its installation use following command:

apt-get install openimscore-fhoss

Post-installation scripts automatically runs configuration wizard in which you are asked to provide:

  • java location directory (debian default is /usr/bin/java)
  • IMS domain name. In our case it's obligatory test1.local
  • Listen IP address (of installed HSS daemon). Type the global IP address through it's available to outside.
  • Public address of your DNS server. In our case it's 158.193.152.2. DNS server is the key komponent in IMS environment for correct SIP nodes discovery funcioning.
  • you will be asked if you want to configure mysql server, select yes
  • next you will be asked for the mysql root password defined during mysql server installation
  • at last step, you have asked for typing usernames for IMS users that will be stored in HSS database (type names separated by spaces). users will have password defined as the same as usernames. so user ims-user will have password ims-user.

Open the main diameter HSS configuration file /etc/fhoss/DiameterPeerHSS.xml:

  • make sure that on all places in this file is correct IMS domain name that you've used (test1.local)
  • Beside this, you need to have following directives defined:
    • One Acceptor tag with global IP address: <Acceptor port="3868" bind="158.193.139.43" />
    • Two Peer tags:
<Peer FQDN="icscf.test1.local" Realm="test1.local" port="3869" />
<Peer FQDN="scscf.test1.local" Realm="test1.local" port="3870" />

both lines defines connection through diameter Cx interface to respective SIP servers (icscf, scscf respectively) to correct ports (on other sides of Cx interfaces you must have running interfaces on defined ports!! - this port configuration is stored on SIP servers in xml files in /etc/kamailio/icscf.xml on I-CSCF or /etc/kamailio/scscf.xml on S-CSCF respectively).

 

In the main HSS webserver configuration file /etc/fhoss/hss.properties, you can change:

  • web server listen address
  • changing default listen port from 8080 to something nicer
  • other configuration options you can ignore for now

After making changes in configuration, you need to restart HSS daemon for applying changes in real:

/etc/init.d/openimscore-fhoss restart

  Afer completition of post-installation script you will have configured mysql server and fhoss will be running. HSS supports only simple administration through the command line:

  • script /usr/sbin/fhoss-add-imscore-user.sh with which you can create new IMS users.

Complete administration interface is provided through web server which is automatically started with FHoSS daemon on port 8080. So you can connect with web browser and navigate to the following link for HSS management:

http://hss.test1.local:8080

You will be asked for credentials for web interface. In default, you can provide this:

  • username: hssAdmin, password: hss, for administrator access
  • username: hss, password: hss, for user view access

You can change this access accounts in file /etc/fhoss/conf/tomcat-users.xml to your needs.

Now you can administer your IMS platform, make calls, analyze traffic and create some useful SIP applications :)

 

HSS Tips and tricks

  • Trouble with user authentication with using some available IMS client.
    • Also if you have right IMS client configuration, right user private identity and password, your client inform you about failed registration proces with message: Authentication failed: 401 - Unauthorized - Challenging the UE
    • The problem is in wrong authentication scheme defined in HSS for registered user (in section of private user identity). Default scheme is Digest-AKAv1-MD5 which may not be supported by your IMS client. Try to use another authentication scheme, i. e. Digest-MD5.
  • When editing authentication scheme of user private identity, make sure that your changes was applied. We have trouble with manually created user account which has in some attributes invalid values:
Please resolve following error(s):
  Please provide a valid AMF (length should be 4)
  Please provide a valid OP (length should be 32)

After cutting the logest strings in that attributes, changes that you've made in user preferences will be applied now.

  • Where can I find logs from HSS?
    • HSS logs are located in /var/log/OpenIMSCore/ directory by default, located in two separated files: hss.activities.log and hss.server.log.

 Testing

Try make a call.

AttachmentSize
File intradomain-call.txt49.96 KB
Groups: