Saturday, November 5, 2011

Diameter - Seagull and jDiameter test cases

This time about Diameter. I will not try to describe this protocol. Breif summarization I put below on simple diagram. For more specific information please refer to RFC 3588.

My main purpose in this series of posts will be to extend previous SIP group example with:

  • getting group's member list from HSS
  • getting user service profile from HSS
  • sending accounting records

But berfore we achive this I will first introduce simple example from which we will start.
As before I will try to show everything step-by-step to get everything working.

Mobicents JSLEE server with Diameter support.

Download latest version from web site, unzip, set JBOSS_HOME environment variable.
Start Mobicent.
Copy Diamater MUX SAR directory from extra/modicents-diameter directory into deploy as you can read from README.
Copy Diameter base RA from resources/diameter-base directory into deploy directory.
You should ended with logs like these one belowe:
Now you have everything with basic configuration. Additional you can check it:
netstat -ant | grep 3868
Before you start to develope any service I admit you to try to write some simple examples. If you want to learn more about Mobicents Diamter API you can find a lot of information in documentation. There is also quite good example on this blog post (one of the Mobicents core member)

You can download simple Diameter example to install on JSLEE which is included within Diameter boundle available on Mobicents website. Version I tried is diameter-base-example-DU-2.4.1.FINAL.jar. Together with binary package there is also source package containing SBB source code. When you copy this JAR to deploy directory service should be properly installed.
Since now everything should be working.

This simple service sends/receives AccountingRequest/AccountingAnswer messages. Client/server mode you  can switch through example.mode variable inside file which is in SBB package.

Diameter service

Before we start writing let's gather some informations:

  • structure of Diamter API
  • Diameter peers' properties to configure both sites
Information for the first point I gathered on simple diagram.
Now second point. As we have to configure both peers we need apropriate data. Let's see what is hold in:

  • resource-adaptor-jar.xml inside base-ra-xx.jar (this package is inside Base Diameter RA)
  • jdiameter-config.xml inside mobicents-diameter-mux-1.4.0.CR1.sar/config directory
In the first file we can find supported applications:
  • authorization 
    • Vendor-ID = 0, Application-Identifier: 0
    • Vendor-ID = 193, Application-Identifier: 19301
  • accounting
    • Vendor-ID = 0, Application-Identifier: 3 - Diameter Base Accounting application as definied in RFC 3588
    • Vendor-ID = 193, Application-Identifier: 19302 

In the second file (from MUX) we can find peers definition:

  • Diameter Identity - aaa:// (which is kind of Diameter URI)
  • realm -
  • peers - aaa://
We have all basic informations. Based on example from Bartosz's blog and Mobicents documentation let's try to wirte simple client application using accounting application, I mean which sends AccountingRequest and receives AccountingAnswer.
Before we start we need to switch SLEE service from client to server mode changing example.mode. So:
  • uninstall service
  • change mode value to: example.mode=server
  • install service again
You shoul see something like this on console:
[DiameterBaseExampleSbb] Diameter Base Example :: Initialized in SERVER mode.
Now we can try to write our application.
In chapter 2.4 of Mobicents Diameter documentation we have some examples. Below I present pom.xml of a new created artifact and code of class containing main() method.

Where we can find our jdiameter config file? We can copy jdiameter-config.xml from MUX config directory (remember, to src/main/resources directory). I have to only change peers configuration to what I note above. So my final configuration looks like that:

So now we can verify does this part of code is working.
mvn exec:java -Dexec.mainClass=""
netstat -ant | grep 21812
We should see that something is listeninig on this port.
There is also a log on console like this:
Failed to initialize and configure Diameter Dictionary
You can also copy dictionary.xml from MUX config directory (as previously copy it to resources directory). So let's initialize dictionary.

No let's check it:
mvn clean install
mvn exec:java -Dexec.mainClass=""
Now is better.
In dictionary you can find AVP, application, command definitions and other usefull definitions.
Let's try to send a message. To make things easier I will take message structure from diameter-base-example. So short summarization of request content:

  • ApplicationId - 19302
  • Session-Id AVP - generated
  • Vendor-Specific-Application-Id AVP
    • Vendor-Id AVP - 193
    • Acct-Application-Id AVP - 19302
  • Origin-Host AVP -
  • Origin-Realm AVP -
  • Destination-Host AVP -
  • Destination-Realm AVP -
  • SCAP-Subscription-Id AVP
    • SCAP-Subscription-Id-Data AVP - 500100200
    • SCAP-Subscription-Id-Type AVP - 0 (END_USER_MSISDN)
  • SCAP-Requested-Service-Unit AVP
    • SCAP-Unit-Value AVP
      • SCAP-Value-Digits AVP - 10
  • Accounting-Record-Type AVP - 1
  • Accounting-Record-Number AVP - 0
  • SCAP-Requested-Action AVP - 0
  • SCAP-Service-Parameter-Info AVP
    • SCAP-Service-Parameter-Type AVP - 0
    • SCAP-Service-Parameter-Value AVP - 510
  • SCAP-Service-Parameter-Info AVP
    • SCAP-Service-Parameter-Type AVP - 14
    • SCAP-Service-Parameter-Value AVP - 20
Remember that you set message ApplicationId as well as Vendor-Specific-Application-Id AVP via ApplicationId object. If you try to create and add Avp.VENDOR_SPECIFIC_APPLICATION_ID it will be ommited.

But when you start it you will get an error.
Exception in thread "main" org.jdiameter.api.RouteException: Unknown realm name []
To resolve this problem first I run Wireshark and verify is there any communication with server. I noticed that there is no Capabiliteis Exchange procedure. When you look into jdiamiter-config.xml you will notice attempt_connect parameter which you have to change to true.
Now is a bit better, I can see CER/CEA exchange.
mvn clean install
mvn exec:java -Dexec.mainClass=""

Now you should see proper request/answer message sequence.
When we know how our message have to look like let's try to write test case using Seagull.

Quick installation:
  • download latest version from (I chose RHEL5U2)
  • unpack it: tar -zxvf seagull*tar.gx
  • change directory: cd packages/
  • install it (as super user): 
    • rpm -ivh seagull-core-1.8.2-linux-2.6-intel.rpm
    • rpm -ivh seagull-diameter-protocol-1.8.2-linux-2.6-intel.rpm
    • install over packages
  • cd /opt/seagull - here should be you installation

$ cd /opt/seagull/diameter/config
$ cp base_rf.xml base_ericsson.xml

Now edit base_ericsson.xml file and:
  • change Accounting-Record-Type to Unsigned32
  • change application-id of ACR, ACA commands to 19302
  • add new AVP as belowe one (all created based on dictionary.xml from jDiameter)

Now we have our seagull dictinoary. Now scenario.
$ cd /opt/seagull/diameter/scenario
$ touch acr-aca.client.xml 
Edit acr-aca.client.xml and paste this content (I created it based on copy of ccr-cca.client.xml)

Now only start script left. 
$ cd /opt/seagull/diameter/run
$ touch start_client_er.ksh

And change all parameters to our new created files:
Now we have only change its attributes to execute as a script
$ chmod u+x start_client_er.ksh
And start it
$ ./start_client_er.ksh
And it should works.

What you get valuable from this tutoria is how to use seagull with your custom application as well as how to create simple client/server application outside of container using jDiameter.
As always below are links to working code:


  1. Hi

    do u know how I can configure seagull to send CER, CCR and DPR in one scenario file?

    - paul

  2. Hi,

    The above project is not working. Can you plz update the pom and upload it again.

    Thanks in advance.

    1. This comment has been removed by the author.