Home › Documentation

OpenIMSCore Installation Guide

Installation Guide

Overview

This page is supposed to help you jump-start the Open IMS Core. In the SVN distribution, the whole things is pre-configured and pre-provisioned with a set of minimal data that should be enough for a simple "Alice-calls-Bob" trial.

Quick Install

If you already went once through the installation procedure, this section will help refresh your memory on what steps you are supposed to follow. If this is your first time, skip over it for now and start with Step 1. 

      	
      	mkdir /opt/OpenIMSCore 
      	cd /opt/OpenIMSCore

      	mkdir FHoSS 
      	svn checkout http://svn.berlios.de/svnroot/repos/openimscore/FHoSS/trunk FHoSS

      	mkdir ser_ims 
      	svn checkout http://svn.berlios.de/svnroot/repos/openimscore/ser_ims/trunk ser_ims

      	cd FHoSS 
      	ant compile deploy 
      	cd ..

      	cd ser_ims 
      	make install-libs all 
      	cd ..

      	mysql -u root -p < FHoSS/scripts/hss_db.sql 
      	mysql -u root -p < FHoSS/scripts/userdata.sql

      	mysql -u root -p < ser_ims/cfg/icscf.sql 

      	cp ser_ims/cfg/*.cfg . 
      	cp ser_ims/cfg/*.xml . 
      	cp ser_ims/cfg/*.sh .

Step 1: Prerequisites

  • Hardware requirements
    • A current Linux desktop class machine should be enough
    • If you want to get ultimate performance:
      • Add several Gigabytes of RAM
      • Have as many CPUs/Cores as
      • Gigabit Ethernet would help
  • Network access
    • A current Linux desktop class machine should be enough
    • Inter-domain NAT is not something we are interested in, so a public IP address would be great
    • Controllable DNS server if you don't want to have one on your Linux box
  • Software requirements
    • ~100 MBytes of disk space to be on the safe side
    • GCC3/4, make, JDK1.5, ant
    • MySQL installed and started (or other DBMS if you can deal with it)
    • bison, flex
    • libxml2 (> 2.6), libmysql - both with development
    • Linux kernel 2.6 and ipsec-tools (setkey) if you want to use IPSec security
    • Optional: openssl if you would like to enable the TLS security
    • bind installed and running (or other name server if you can deal with it)
    • Browser on the box or that can connect to the box (for user provisioning)

      • Note: we consider that you have all this installed, configured and running.

      Note: we assume for now that you want to install the whole thing on just 1 box.

Step 2: Get the Source Code

Step 3: Compile

  • ser_ims
    • New!!! Do "make install-libs all" in ser_ims

      cd ser_ims
make install-libs all
cd ..
    • If something breaks, you probably don't have all the prerequisites.
  • FHoSS
    • If you don't have a JDK >=1.5, get one before proceeding
    • Make sure, that the JDK version that you are using is >= 1.5!!!
      # java -version
java version "1.5.0_07"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_07-b03)
Java HotSpot(TM) Client VM (build 1.5.0_07-b03, mixed mode)

      It is often the case that users have just installed a 1.5 JDK but they are
      still using their old JDK installation! If you see lots of errors, recheck
      this before posting a bug report!

    • Do "ant compile deploy" in FHoSS
      New!!! "ant gen" is not needed any more!!!

      cd FHoSS
ant compile
ant deploy
cd ..
  • While you wait for the compilation to finish, you can go ahead and perform Step 4.

Step 4: Configure the Environment

  • Notes:
    • All the installation examples configured to work only on the local loopback
      and the default domain configured as "open-ims.test".
    • The MySQL access rights are set only for local access
    • We recommend that you try it first like this and then do your changes:
      • Replace 127.0.0.1 where required with your IP address
      • Replace the home domain (open-ims.test) with your own one
      • Change the database passwords

      For this operation the ser_ims/cfg/configurator.sh might help you.

  • DNS
    • A sample DNS zone file can be found in ser_ims/cfg/open-ims.dnszone
    • Copy it to your bind configuration directory
    • Edit named.conf and insert the file there (Would be great to also add reverse DNS entries)
    • Restart the name server
    • Test that the names are resolvable (don't forget about /etc/resolv.conf pointing to your new DNS server!)
  • MySQL
    • Run the SQL dumps (mysql -u root -p -h localhost < dump.sql):
      New!!! "hssdb.sql" was replaced by "hss_db.sql" !!!

      mysql -u root -p -h localhost < ser_ims/cfg/icscf.sql
mysql -u root -p -h localhost < FHoSS/scripts/hss_db.sql  
mysql -u root -p -h localhost < FHoSS/scripts/userdata.sql
    • Check if the databases are in there and accessible

Step 5: Configure the IMS Core

  • By now you should have MySQL and DNS working
  • CSCFs
    • Copy the following files to /opt/OpenIMSCore or another location comfortable for you:
      pcscf.cfg, pcscf.sh, icscf.cfg, icscf.xml, icscf.sh, scscf.cfg, scscf.xml, scscf.sh, 

      cp ser_ims/cfg/*.cfg . 
cp ser_ims/cfg/*.xml . 
cp ser_ims/cfg/*.sh .
  • FHoSS

    • Take a look at the configuration files in FHoSS/deploy/ (available after Step 3 completes)
  • Edit these files to your own preferences (don't forget to update the DNS zone file accordingly and restart the name server)

Step 6: Start the components

  • CSCFs
    • Start pcscf.sh, icscf.sh and scscf.sh
    • All these should run in parallel.
    • We love debugging, so by default they would stay in foreground.
    • By default you should see periodically log messages with the content of the registrar and with the opened diameter links
  • FHoSS
    • Start FHoSS/deploy/startup.sh
    • If the previous step fails, check that you have the JAVA_HOME environment variable correctly exported and/or modify the script that you just tried to start.
    • Check the web interface on http://localhost:8080/
    • Check if the Diameter Peers are connecting to each other. You can see this in the console of FHoSS or in that of I/S-CSCF

Step 7: Configure Subscribers

  • FHoSS
    • By default, FHoSS comes provisioned with a couple of sample users:
    • Use these or insert new ones.
      • Create a Subscription
      • Create a Private Identity
      • Create a Public Identity
      • Link them
  • SIP-to-IMS Gateway
    • The SIP-to-IMS Gateway is now obsolete and was droped from the project. See the Annex and FAQ for information
      on how you can use the Open IMS Core with SIP clients capable of only MD5 authentication.
  • IMS User Endpoint Configuration
    • Provision with your own UE data or use one of the default users
    • Alice:
      • Private Identity: alice@open-ims.test
      • Secret Key: alice
      • OP: 0x00...0
      • AMF: 0x00...0
      • Use of Anonimity Key: enable
      • Public Identity: sip:alice@open-ims.test
      • Realm: open-ims.test
      • Strict Outbound Proxy: sip:pcscf.open-ims.test:4060
    • Bob: similar
  • SIP User Endpoint Configuration
    • Alice:
      • User part of the SIP URI: alice
      • Host part of the SIP URI/Domain/realm: open-ims.test
      • Password: alice
      • Strict Outbound Proxy: sip:pcscf.open-ims.test:4060
      • !!! Make sure that your SIP client does REGISTER sip:open-ims.test and not REGISTER sip:pcscf.open-ims.test:4060
      • !!! Read the Annex and FAQ related to using MD5-only clients with the Open IMS Core
    • Bob: similar

Step 8: Test!

  • This is the last step. You should have all installed and configured by now
  • Registration uses all components and as such, it is a good test if all is up & running
  • Use Wireshark to see what's going on:
    • Monitor ports 4060, 5060 and 6060 for SIP traffic
    • Monitor ports 3868, 3869 and 3870 for Diameter traffic

Annex A - DNS HOWTO

A lot of users seem to have difficulties when setting up a DNS server. Although it is not our
purpose to teach you this, here is a summary of this process. But be aware that this does not means that we
are offering any further support for it and you don't have to read the DNS manual. If you think that
/etc/hosts would be enough, you are wrong as it can not help you with special DNS queries like NAPTR and SRV.

So how do you get a DNS server up and running?

  • Get the bind (or often called named) package installed on your distribution
  • Make sure you are root
  • Locate named.conf (could be in /etc or /etc/bind or /etc/named)
  • Edit that file according to your needs. Here are some things that you need in there:
    options {
	...
	forward first;
	forwarders {
	    {THE_IP_ADDRESS_OF_YOUR_UPSTREAM_DNS_SERVER;}  ;
	};
	...
};
...

zone "open-ims.test" IN {
	type master;
	file "pri/open-ims.dnszone";
	notify no;
};
...

    On some distributions this file includes other files so be sure to dig through those also.
    THE_IP_ADDRESS_OF_YOUR_UPSTREAM_DNS_SERVER can be found in /etc/resolv.conf.

  • Now copy the file /opt/OpenIMSCore/ser_ims/cfg/open-ims.dnszone to where you configure it above
    (pri/open-ims.dnszone)

    cp /opt/OpenIMSCore/ser_ims/cfg/open-ims.dnszone /var/bind/pri/
chown -R named:named /var/bind/pri/open-ims.dnszone
  • Then start or re-start the DNS server (remember that these configuration files are not monitored
    for changes so you will have to send a SIGHUP or do a restart to reload them).

    /etc/init.d/named restart
  • You should now test if it works. In the response look if you got the correct answer.
    dig @127.0.0.1 pcscf.open-ims.test
  • To actually use it, you would need to configure it as a DNS server for your machine. Here is
    how your /etc/resolv.conf file should look like:

    # cat /etc/resolv.conf
nameserver 127.0.0.1
search open-ims.test
domain open-ims.test
  • Remember that utilities like the DHCP-Client overwrite this file be default!

Annex B - SIP Clients How-To

The old SIP2IMS module that was performing MD5-to-AKA authentication translation has been deleted as being
obsolete as the core can perform MD5 authentication too. Another reason is that it's functionality was seriously
flawed by the fact that it was a SIP proxy rather than a full B2BUA.

So how do you get a client registered?

  • First provision the users (or use the default sip:alice@open-ims.test or sip:bob@open-ims.test).
    Make sure than in the HSS provisioning interface in the private identity configuration, you allow the
    use of Digest-MD5 for the respective users
  • Then you have two options for the S-CSCF to trigger an MD5 authentication
    1. Modify the client to send a parameter "algorithm=MD5" in the Authorization header in the first
      unauthorized REGISTER.
    2. Or modify the scscf.cfg and enable the MD5 authorization as the default authentication method instead
      of AKAv1-MD5.
  • Next just make sure that the client is using the P-CSCF address (sip:pcscf.open-ims.test:4060 by default) as
    strict outbound proxy and the REGISTER Request-URI is "sip:open-ims.test" (or your own domain name) and not
    "sip:pcscf.open-ims.test:4060" as many SIP clients fail here.

Annex C - Changing the Domain Name and IP-Address of configuration files

OpenIMSCore is preconfigured to work with the domain "open-ims.test" and ip address of default loopback device, "127.0.0.1".
Following the installation instructions above without changing the configuration files would set up this environment
successfully. For some reasons(like testing roaming,communicating with other external entitites), you would need
to change the domain name. In that case you could use a configuration script(configurator.sh) which is stored under
directory /opt/OpenIMSCore/ser_ims/cfg/

Does it only change *.cfg files?

No, it can also reconfigure *.xml , *.sql and FHoSS configuration files(*.properties).

How do I make use of configurator.sh?

  • You can directly execute it and fetch the files to be changed as arguments. See the example
    below:

       
 # pwd    
 /opt/OpenIMSCore
 # ser_ims/cfg/configurator.sh ser_ims/cfg/scscf.cfg ser_ims/cfg/icscf.xml \ 
         FHoSS/deploy/hss_db.sql FHoSS/deploy/hss.properties
  • Then copy the files to the /opt/OpenIMSCore directory
  • Note that you have to backup your configuration files that you want to reconfigure