Ngun: http://www.openimscore.

org/installation_guide

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
o A current Linux desktop class machine should be enough
o

If you want to get ultimate performance:

Add several Gigabytes of RAM

Have as many CPUs/Cores as

Gigabit Ethernet would help

Network access
o

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
o

~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?
o

The CSCFs: ser_ims/trunk

The HSS: FHoSS/trunk

How? - The source code is pre-configured to work from a standard file path:
o

Create /opt/OpenIMSCore and go there

mkdir /opt/OpenIMSCore
cd /opt/OpenIMSCore

o
o

Create a new directory ser_ims and checkout the CSCFs there:

o
o

Create a new directory FHoSS and checkout the HSS there:

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

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

Step 3: Compile

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

o
o

cd ser_ims
make install-libs all
cd ..

If something breaks, you probably don't have all the prerequisites.

FHoSS
o

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!!!

o
o
o

# java -version
java version "1.5.0_07"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_07b03)
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!!!

o
o
o

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:
o

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
o

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
o

Run the SQL dumps (mysql -u root -p -h localhost < dump.sql):

New!!! "hssdb.sql" was replaced by "hss_db.sql" !!!

o
o
o
o

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
o

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,

o
o
o

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

FHoSS
o

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
o

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
o

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
o

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
o

By default, FHoSS comes provisioned with a couple of sample users:

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

o

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

o

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:

o

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@openims.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.openims.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