Home › Documentation

OpenIMSCore Installation Guide

Installation Guide

  • Overview
  • Quick Install
  • Step 1: Prerequisites
  • Step 2: Get the Source Code
  • Step 3: Compile
  • Step 4: Configure the Environment
  • Step 5: Configure the IMS Core
  • Step 6: Start the components
  • Step 7: Configure Subscribers
  • Step 8: Test!
  • Annex A - DNS HOWTO
  • Annex B - SIP Clients How-To
  • Annex C - Changing the Domain Name and IP-Address of configuration files

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

  • Where? - Fresh code at http://svn.berlios.de/svnroot/repos/openimscore
    (you will need to have Subversion installed).
    On this page you can find a lot more information about the sources.
  • What?
      □ The CSCFs: ser_ims/trunk
      □ The HSS: FHoSS/trunk
  • How? - The source code is pre-configured to work from a standard file path:
      □ Create /opt/OpenIMSCore and go there

        mkdir /opt/OpenIMSCore
        cd /opt/OpenIMSCore

      □ Create a new directory ser_ims and checkout the CSCFs there:

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

      □ Create a new directory FHoSS and checkout the HSS there:

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

      □ If you would prefer another path, be prepared to edit the configuration
        files!

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:
          ☆ alice@open-ims.test
          ☆ bob@open-ims.test
      □ 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

  • CSCF
  • HSS
  • I-CSCF
  • P-CSCF
  • S-CSCF
  • FHoSS
  • ser_ims

  • Login or register to post comments

Copyright © 2004-2008 Fraunhofer FOKUS NGNI. All rights reserved.
Send feedback about the website or general questions about Open-IMS to: info
-at- open-ims -dot- org

