JBoss.orgCommunity Documentation

SIP Servlets Server User Guide

The Guide to the SIP Servlets v1.1-Certified Server

by Douglas Silas, Jean Deruelle, Vladimir Ralev, Ivelin Ivanov, and Jared Morgan

Abstract

Mobicents is the first and only open source VoIP platform certified for JAIN SLEE 1.0 and SIP Servlets 1.1 compliance. Mobicents serves as a high-performance core for Service Delivery Platforms (SDPs) and IP Multimedia Subsystems (IMSs) by leveraging J2EE to enable the convergence of data and video in Next-Generation Intelligent Network (NGIN) applications.

The Mobicents enables the composition of predefined Service Building Blocks (SBBs) such as Call-Control, Billing, User-Provisioning, Administration and Presence-Sensing. Out-of-the-box monitoring and management of Mobicents components is achieved through JMX Consoles. JSLEE allows popular protocol stacks such as SIP to be plugged in as Resource Adapters (RAs), and Service Building Blocks—which share many similarities with EJBs—allow the easy accommodation and integration of enterprise applications with end points such as the Web, Customer Relationship Management (CRM) systems and Service-Oriented Architectures (SOAs). The Mobicents is the natural choice for telecommunication Operations Support Systems (OSSs) and Network Management Systems (NMSs).

In addition to the telecommunication industry, the Mobicents is suitable for a variety of problem domains demanding an Event-Driven Architecture (EDA) for high-volume, low-latency signaling, such as financial trading, online gaming, (RFID) sensor network integration, and distributed control.


Preface
1. Document Conventions
1.1. Typographic Conventions
1.2. Pull-quote Conventions
1.3. Notes and Warnings
1. Introduction to the SIP Servlets Server
1.1. High-Availability: SIP Servlets Server Load Balancing, Clustering and Failover
1.2. Working with the SIP Servlets Management Console
2. SIP Servlets Server-Installing, Configuring and Running
2.1. SIP Servlet-Enabled JBoss Application Server: Installing, Configuring and Running
2.1.1. Java Development Kit (JDK): Installing, Configuring and Running
2.1.2. Pre-install Requirements and Prerequisites
2.1.3. Downloading
2.1.4. Installing
2.1.5. Setting the JBOSS_HOME Environment Variable
2.1.6. Configuring
2.1.7. Running
2.1.8. Using
2.1.9. Testing
2.1.10. Stopping
2.1.11. Uninstalling
2.2. SIP Servlet-Enabled Tomcat Servlet Container: Installing, Configuring and Running
2.2.1. Java Development Kit (JDK): Installing, Configuring and Running
2.2.2. Pre-Install Requirements and Prerequisites
2.2.3. Downloading
2.2.4. Installing
2.2.5. Setting the CATALINA_HOME Environment Variable
2.2.6. Configuring
2.2.7. Running
2.2.8. Stopping
2.2.9. Using
2.2.10. Testing
2.2.11. Uninstalling
2.3. Configuring
2.3.1. Configuring SIP Connectors
2.3.2. Application Routing and Service Configuration
2.3.3. SIP Servlets Server Logging
3. Application Router
3.1. Default Application Router
3.1.1. Role of the Application Router
3.1.2. Mobicents Default Application Router
3.1.3. Limitations of the Default Application Router
3.2. DFC Application Router
3.2.1. Description of DFC Application Router
3.2.2. Installing the DFC Application Router
4. SIP Servlet Example Applications
4.1. Operating the Example Applications
4.1.1. The Location Service
4.1.2. The Diameter Event-Changing Service
4.1.3. The Call-Blocking Service
4.1.4. The Call-Forwarding Service
4.1.5. The Call-Controller Service
4.1.6. Media IPBX
5. Clustering and High Availability
5.1. Mobicents SIP Servlets for JBoss: Clustering Support
5.1.1. SIP Servlets Server Cluster: Installing, Configuring and Running
5.2. Mobicents SIP Servlets for JBoss: Transparent Failover
5.2.1. MSS for JBoss Cluster: Installing, Configuring and Running
5.3. Load Balancer
5.3.1. SIP Load Balancing Basics
5.3.2. HTTP Load Balancing Basics
5.3.3. Pluggable balancer algorithms
5.3.4. Distributed load balancing
5.3.5. Implementation of the Mobicents Load Balancer
5.3.6. SIP Message Flow
5.3.7. SIP Load Balancer: Installing, Configuring and Running
5.3.8. IP Load Balancing
6. Enterprise Monitoring and Management
6.1. Mobicents SIP Servlets Monitoring and Management
6.1.1. Installation of the Enterprise Monitoring and Management Console
6.1.2. Usage Instructions
6.2. SIP Load Balancer Monitoring and Management
6.2.1. Installation of the Enterprise Monitoring and Management Console
6.2.2. Usage Instructions
7. Advanced Features of the SIP Servlets Server
7.1. Media Support
7.1.1. JSR 309 : Media Server Control API
7.1.2. Mobicents Media Server Control API (MSC API)
7.2. Concurrency and Congestion Control
7.3. SIP Servlets Application Security
7.4. STUN Support
7.5. Seam Telco Framework
7.6. Diameter Support
7.7. SIP and IMS Extensions
7.8. JRuby/Rails Integration with Torquebox Telco Framework
7.9. SIP Servlets - JAIN SLEE Interoperability
7.10. Eclipse IDE Tools
7.10.1. Pre-Install requirements
7.10.2. Installation
7.10.3. SIP Servlets Core Plug-in
7.10.4. SIP Phone Plug-in
8. Best Practices
8.1. Mobicents SIP Servlets Performance Tips
8.1.1. Tuning JBoss
8.1.2. Tuning Mobicents SIP Servlets
8.1.3. Tuning The JAIN SIP Stack
8.1.4. Tuning The JVM
8.1.5. Tuning The Operating System
8.2. NAT Traversal
8.2.1. STUN
8.2.2. TURN
8.2.3. ICE
8.2.4. Other Approaches
A. Revision History

This manual uses several conventions to highlight certain words and phrases and draw attention to specific pieces of information.

In PDF and paper editions, this manual uses typefaces drawn from the Liberation Fonts set. The Liberation Fonts set is also used in HTML editions if the set is installed on your system. If not, alternative but equivalent typefaces are displayed. Note: Red Hat Enterprise Linux 5 and later includes the Liberation Fonts set by default.

Four typographic conventions are used to call attention to specific words and phrases. These conventions, and the circumstances they apply to, are as follows.

Mono-spaced Bold

Used to highlight system input, including shell commands, file names and paths. Also used to highlight key caps and key-combinations. For example:

The above includes a file name, a shell command and a key cap, all presented in Mono-spaced Bold and all distinguishable thanks to context.

Key-combinations can be distinguished from key caps by the hyphen connecting each part of a key-combination. For example:

The first sentence highlights the particular key cap to press. The second highlights two sets of three key caps, each set pressed simultaneously.

If source code is discussed, class names, methods, functions, variable names and returned values mentioned within a paragraph will be presented as above, in Mono-spaced Bold. For example:

Proportional Bold

This denotes words or phrases encountered on a system, including application names; dialogue box text; labelled buttons; check-box and radio button labels; menu titles and sub-menu titles. For example:

The above text includes application names; system-wide menu names and items; application-specific menu names; and buttons and text found within a GUI interface, all presented in Proportional Bold and all distinguishable by context.

Note the > shorthand used to indicate traversal through a menu and its sub-menus. This is to avoid the difficult-to-follow 'Select Mouse from the Preferences sub-menu in the System menu of the main menu bar' approach.

Mono-spaced Bold Italic or Proportional Bold Italic

Whether Mono-spaced Bold or Proportional Bold, the addition of Italics indicates replaceable or variable text. Italics denotes text you do not input literally or displayed text that changes depending on circumstance. For example:

Note the words in bold italics above username, domain.name, file-system, package, version and release. Each word is a placeholder, either for text you enter when issuing a command or for text displayed by the system.

Aside from standard usage for presenting the title of a work, italics denotes the first use of a new and important term. For example:

Mobicents SIP (Session Initiation Protocol) Servlets deliver a consistent, open platform on which to develop and deploy portable and distributed SIP and Java Enterprise Edition services. The Mobicents SIP Servlets Server is a certified implementation of the SIP Servlet v1.1 (JSR 289) specification that can run on top of either the JBoss Application Server or the Tomcat Servlet Container.

Mobicents SIP Servlets for JBoss (MSS for JBoss) strives to develop interoperability standards between SIP Servlets and the Java Service Logic Execution Environment (JSLEE) so that applications can exploit the strengths of both. The JAIN-SIP Reference Implementation is leveraged as the SIP stack, and the Mobicents JAIN SLEE Server is used as the SLEE implementation.

Telecommunications applications demand High-Availability (HA), fault tolerance, scalability and performance. Providing highly-available end-user applications that are tolerant of faults is commonly achieved through the use of clustering technologies.

Clustering is a complex subject that is often used to collectively address a variety of techniques aimed at improving the high-availability and scalability of services and applications. Such techniques include distributed state replication, load balancing, and failover capabilities. The usage of any one of these techniques improves either reliability or performance, but for the sake of the other. It requires careful analysis of real-world scenarios to arrive at an architecture which represents the optimal balance of performance and reliability.

Based on experience with production deployments and extensive feedback from the Open Source community, Mobicents HA has undergone several iterations of refinement. In its current incarnation, the architecture can be described as a "star topology" with symmetric application servers and a smart, lightweight load-balancing element with built-in failover logic. The amount of state replication is kept to a minimum for maximum scalability with sufficiently-high reliability.

Clustering Terms and Definitions for Mobicents SIP Servlets

For purposes of clarity, the SIP Servlets High-Availability sections use terms—such as cluster—with meanings specific to the context of Mobicents SIP Servlets. Therefore, the following definitions are provided to clarify more precisely what is meant by the terms cluster, node, SIP Servlets Server and so on, in the subsequent sections, and in the context of Mobicents High-Availability.

The Mobicents SIP Servlets Server can run on either the JBoss Application Server or the Tomcat Servlet Container. This section details how to install the SIP Servlets Server on top of the JBoss Application Server. For installation instructions for the Tomcat Servlet Container, refer to Section 2.2, “SIP Servlet-Enabled Tomcat Servlet Container: Installing, Configuring and Running”

Note

It is recommended that the SIP Servlets Server is run on the JBoss platform. Some functionality, including the ability to execute some SIP Extension examples, is not available in the Tomcat version.

Differences Between a Standard JBoss Installation and the Mobicents SIP Servlets Version

Provided here is a list of differences between a standard JBoss Application Server installation one customized for SIP Servlets. The differences include:

  • The server/default/deploy directory contains both HTTP and SIP Servlet applications (WAR and SAR2 files).

  • The server/default/deploy/jboss-web.deployer and server/default/deploy/jbossweb.sar units have been modified to provide extended classes to the standard JBoss container classes, in order to allow SIP applications to be loaded and the SIP stack to be started.

  • The server/default/deploy/jboss-web.deployer and server/default/deploy/jbossweb.sar context.xml files have been modified to allow the extended manager to manage SIP sessions and SIP application sessions in addition to HTTP sessions.

  • The server/default/deploy/jbossweb.sar/ server.xml file has been modified to provide extended classes to common JBoss Web containers. The classes allow SIP applications to be loaded, and the SIP stack to be started.

  • The server/default/deploy/jbossweb.sar/ jboss-beans.xml file has been modified to allow the JBoss container to process SIP messages.

  • The server/default/deployers/ metadata-deployer-jboss-beans.xml file has been modified to allow JBoss to parse sip.xml deployment descriptors and SIP metadata annotations.

  • The server/default/deploy/jboss-web.deployer/META-INF/jboss-service.xml file and the server/default/deploy/jboss-web.deployer/META-INF/webserver-xmbean.xml file have been modified so that it is now possible for JBoss containers to correctly deploy SIP servlets and converged applications.

  • A dars directory containing all of the Default Application Router (DAR) properties files for using the various SIP Servlets applications (which come bundled with the release) has been added to the server/default/conf directory.

  • Additional JAR files have been added to enable SIP Servlet functionality; these are located in the server/default/deploy/jboss-web.deployer/ and server/default/deploy/jbossweb.sar/ directories.

The Mobicents Platform is written in Java; therefore, before running any Mobicents server, you must have a working Java Runtime Environment (JRE) or Java Development Kit (JDK) installed on your system. In addition, the JRE or JDK you are using to run Mobicents must be version 5 or higher[1].

Should I Install the JRE or JDK?

Although you can run Mobicents servers using the Java Runtime Environment, we assume that most users are developers interested in developing Java-based, Mobicents-driven solutions. Therefore, in this guide we take the tact of showing how to install the full Java Development Kit.

Should I Install the 32-Bit or the 64-Bit JDK, and Does It Matter?

Briefly stated: if you are running on a 64-Bit Linux or Windows platform, you should consider installing and running the 64-bit JDK over the 32-bit one. Here are some heuristics for determining whether you would rather run the 64-bit Java Virtual Machine (JVM) over its 32-bit cousin for your application:

  • Wider datapath: the pipe between RAM and CPU is doubled, which improves the performance of memory-bound applications when using a 64-bit JVM.

  • 64-bit memory addressing gives virtually unlimited (1 exabyte) heap allocation. However large heaps affect garbage collection.

  • Applications that run with more than 1.5 GB of RAM (including free space for garbage collection optimization) should utilize the 64-bit JVM.

  • Applications that run on a 32-bit JVM and do not require more than minimal heap sizes will gain nothing from a 64-bit JVM. Barring memory issues, 64-bit hardware with the same relative clock speed and architecture is not likely to run Java applications faster than their 32-bit cousin.

Note that the following instructions detail how to download and install the 32-bit JDK, although the steps are nearly identical for installing the 64-bit version.

Downloading

You can download the Sun JDK 5.0 (Java 2 Development Kit) from Sun's website: http://java.sun.com/javase/downloads/index_jdk5.jsp. Click on the Download link next to "JDK 5.0 Update <x>" (where <x> is the latest minor version release number). On the next page, select your language and platform (both architecture—whether 32- or 64-bit—and operating system), read and agree to the Java Development Kit 5.0 License Agreement, and proceed to the download page.

The Sun website will present two download alternatives to you: one is an RPM inside a self-extracting file (for example, jdk-1_5_0_16-linux-i586-rpm.bin), and the other is merely a self-extracting file (e.g. jdk-1_5_0_16-linux-i586.bin). If you are installing the JDK on Red Hat Enterprise Linux, Fedora, or another RPM-based Linux system, we suggest that you download the self-extracting file containing the RPM package, which will set up and use the SysV service scripts in addition to installing the JDK. We also suggest installing the self-extracting RPM file if you will be running Mobicents in a production environment.

Installing

The following procedures detail how to install the Java Development Kit on both Linux and Windows.

Important

You do not need to install a -compat package in addition to the JDK if you installed the self-extracting RPM file! The -compat package merely performs the same SysV service script set up that the RPM version of the JDK installer does.

Configuring

Configuring your system for the JDK consists in two tasks: setting the JAVA_HOME environment variable, and ensuring that the system is using the proper JDK (or JRE) using the alternatives command. Setting JAVA_HOME usually overrides the values for java, javac and java_sdk_1.5.0 in alternatives, but we will set them all just to be safe and consistent.

Setting the JAVA_HOME Environment Variable on Generic Linux

After installing the JDK, you must ensure that the JAVA_HOME environment variable exists and points to the location of your JDK installation.

Setting the JAVA_HOME Environment Variable on Linux

You can determine whether JAVA_HOME is set on your system by echoing it on the command line:

~]$ echo $JAVA_HOME

If JAVA_HOME is not set already, then you must set its value to the location of the JDK installation on your system. You can do this by adding two lines to your personal ~/.bashrc configuration file. Open ~/.bashrc (or create it if it doesn't exist) and add a line similar to the following one anywhere inside the file:

export JAVA_HOME="/usr/lib/jvm/jdk1.5.0_<version>"

You should also set this environment variable for any other users who will be running Mobicents (any environment variables exported from ~/.bashrc files are local to that user).

Setting java, javac and java_sdk_1.5.0 Using the alternatives command
Selecting the Correct System JVM on Linux using alternatives

On systems with the alternatives command, including Red Hat Enterprise Linux and Fedora, you can easily choose which JDK (or JRE) installation you wish to use, as well as which java and javac executables should be run when called.

As the root user, call /usr/sbin/alternatives with the --config java option to select between JDKs and JREs installed on your system:

root@localhost ~]$ /usr/sbin/alternatives --config java

There are 3 programs which provide 'java'.

  Selection    Command
-----------------------------------------------
   1           /usr/lib/jvm/jre-1.5.0-gcj/bin/java
   2           /usr/lib/jvm/jre-1.6.0-sun/bin/java
*+ 3         /usr/lib/jvm/jre-1.5.0-sun/bin/java


Enter to keep the current selection[+], or type selection number:

In our case, we want to use the Sun JDK, version 5, that we downloaded and installed, to run the java executable. In the alternatives information printout above, a plus (+) next to a number indicates the one currently being used. As per alternatives' instructions, pressing Enter will simply keep the current JVM, or you can enter the number corresponding to the JVM you would prefer to use.

Repeat the procedure above for the javac command and the java_sdk_1.5.0 environment variable, as the root user:

~]$ /usr/sbin/alternatives --config javac
~]$ /usr/sbin/alternatives --config java_sdk_1.5.0
Setting the JAVA_HOME Environment Variable on Windows

For information on how to set environment variables in Windows, refer to http://support.microsoft.com/kb/931715.

Testing

Finally, to make sure that you are using the correct JDK or Java version (5 or higher), and that the java executable is in your PATH, run the java -version command in the terminal from your home directory:

~]$ java -version
java version "1.5.0_16"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_16-b03)
Java HotSpot(TM) Client VM (build 1.5.0_16-b03, mixed mode, sharing)
Uninstalling

There is usually no reason (other than space concerns) to remove a particular JDK from your system, given that you can switch between JDKs and JREs easily using alternatives, and/or by setting JAVA_HOME.

Uninstalling the JDK on Linux

On RPM-based systems, you can uninstall the JDK using the yum remove <jdk_rpm_name> command.

Uninstalling the JDK on Windows

On Windows systems, check the JDK entry in the Start menu for an uninstall command, or use Add/Remove Programs.

The latest version of Mobicents SIP Servlets for JBoss is available from http://www.mobicents.org/mss-downloads.html. The top row of the table contains the latest version.

Each version of the SIP Servlets Server is comprised of two separate binary distribution files: one which is MSS for JBoss, and the other which is MSS for Tomcat. Download SIP Servlets Server for JBoss and continue with the following instructions.

Once the requirements and prerequisites have been met and you have downloaded the binary distribution zip file, you are ready to install the MSS for JBoss binary distribution. Follow the instructions below for the selected platform, whether Linux or Windows.

Configuring MSS for JBoss consists of setting the JBOSS_HOME environment variable and optionally customizing the MSS for JBoss server by adding SIP Connectors, configuring the application router, and logging.

After setting JBOSS_HOME according to the instructions in the following section, refer to Section 2.3, “Configuring” to learn how to configure MSS for JBoss.

Alternatively, after having set JBOSS_HOME, the MSS for JBoss server can be run. Return to this section to configure it later.

The Mobicents Platform (Mobicents) is built on top of the JBoss Application Server (JBoss AS). You do not need to set the JBOSS_HOME environment variable to run any of the Mobicents Platform servers unless JBOSS_HOME is already set.

The best way to know for sure whether JBOSS_HOME was set previously or not is to perform a simple check which may save you time and frustration.

Checking to See If JBOSS_HOME is Set on Unix

At the command line, echo $JBOSS_HOME to see if it is currently defined in your environment:

~]$ echo $JBOSS_HOME

The Mobicents Platform and most Mobicents servers are built on top of the JBoss Application Server (JBoss AS). When the Mobicents Platform or Mobicents servers are built from source, then JBOSS_HOME must be set, because the Mobicents files are installed into (or “over top of” if you prefer) a clean JBoss AS installation, and the build process assumes that the location pointed to by the JBOSS_HOME environment variable at the time of building is the JBoss AS installation into which you want it to install the Mobicents files.

This guide does not detail building the Mobicents Platform or any Mobicents servers from source. It is nevertheless useful to understand the role played by JBoss AS and JBOSS_HOME in the Mobicents ecosystem.

The immediately-following section considers whether you need to set JBOSS_HOME at all and, if so, when. The subsequent sections detail how to set JBOSS_HOME on Unix and Windows

You DO NOT NEED to set JBOSS_HOME if...
You MUST set JBOSS_HOME if...

Naturally, if you installed the Mobicents Platform or one of the Mobicents server binary releases which do not bundle JBoss AS, yet requires it to run, then you should install JBoss AS before setting JBOSS_HOME or proceeding with anything else.

Setting the JBOSS_HOME Environment Variable on Unix

The JBOSS_HOME environment variable must point to the directory which contains all of the files for the Mobicents Platform or individual Mobicents server that you installed. As another hint, this topmost directory contains a bin subdirectory.

Setting JBOSS_HOME in your personal ~/.bashrc startup script carries the advantage of retaining effect over reboots. Each time you log in, the environment variable is sure to be set for you, as a user. On Unix, it is possible to set JBOSS_HOME as a system-wide environment variable, by defining it in /etc/bashrc, but this method is neither recommended nor detailed in these instructions.

Procedure 2.5. To Set JBOSS_HOME on Unix...

  1. Open the ~/.bashrc startup script, which is a hidden file in your home directory, in a text editor, and insert the following line on its own line while substituting for the actual install location on your system:

    export JBOSS_HOME="/home/<username>/<path>/<to>/<install_directory>"
  2. Save and close the .bashrc startup script.

  3. You should source the .bashrc script to force your change to take effect, so that JBOSS_HOME becomes set for the current session[2].

    ~]$ source ~/.bashrc
  4. Finally, ensure that JBOSS_HOME is set in the current session, and actually points to the correct location:

    Note

    The command line usage below is based upon a binary installation of the Mobicents Platform. In this sample output, JBOSS_HOME has been set correctly to the topmost_directory of the Mobicents installation. Note that if you are installing one of the standalone Mobicents servers (with JBoss AS bundled!), then JBOSS_HOME would point to the topmost_directory of your server installation.

    ~]$ echo $JBOSS_HOME
    /home/silas/mobicents-all-1.2.1.GA-jboss-4.2.3.GA/jboss/
Setting the JBOSS_HOME Environment Variable on Windows

The JBOSS_HOME environment variable must point to the directory which contains all of the files for the Mobicents Platform or individual Mobicents server that you installed. As another hint, this topmost directory contains a bin subdirectory.

For information on how to set environment variables in recent versions of Windows, refer to http://support.microsoft.com/kb/931715.

To start the server, execute one of the startup scripts in the bin directory (on Linux or Windows), or by double-clicking the run.bat executable batch file in that same directory (on Windows only). It is recommended that the JBoss Application Server is started using the terminal or Command Prompt because the messages displayed during startup can be used to debug, and subsequently correct, any problems. In the Linux terminal or Command Prompt, a successfully started server will return the following information (ending with "Started in 23s:648ms"):

17:48:01,247 INFO  [Server] JBoss (MX MicroKernel) [4.2.2.GA (build: SVNTag=JBoss_4_2_2_GA date=200710221139)] Started in 20s:861ms

Detailed instructions are given below, arranged by platform.

After installation, there should be one pre-configured sample application deployed in the default server onfiguration. You can use it to verify that the server is installed and running correctly. The application name is “org.mobicents.servlet.sip.example.SimpleApplication”. From the Sip Servlets Management Console you can make sure it is subscribed to receive INVITE and REGISTER SIP requests. It is a simple Click2Call application allowing SIP registration and calling phones from the Web user interface.

The scenario for this example consists of the following steps:

Procedure 2.8. Testing the Click2Call sample application

  1. Open up a browser to http://localhost:8080/click2call/. If you have no registered SIP clients you will be asked to register at least two.

  2. Configure your SIP clients to use the sip servlets server as a register and proxy. (IP address : 127.0.0.1, port: 5080) By default it will accept any password

  3. After the registration you will see a table where each cell will initiate a call between the corresponding clients.

  4. Close the calls.

  5. Navigate to http://localhost:8080/click2call/simplecall.html, which is a simplified version that doesn't require registered clients.

  6. Enter the URIs of the two SIP phones you just started and click "Submit"

  7. The phones should be ringing again. You can pick them up and you will know that the SIP and the HTTP containers are working properly.

You can also run Mobicents SIP Servlets on top of the Apache Tomcat Servlet Container. This section provides information on the requirements and prerequisites for running MSS for Tomcat, as well as instructions on how to download, install, configure, run, use, stop, test and uninstall it.

Keep in mind that not all capabilities provided by running Mobicents SIP Servlets Server on top of the JBoss Application Server are available with MSS for Tomcat. In particular, MSS for Tomcat lacks support for both clustering and failover; MSS for Tomcat nodes can utilize the SIP load balancer, however.

If you are interested in clustering and failover support, or would rather run the Mobicents SIP Servlets Server on top of the JBoss Application Server, go to Section 2.1, “SIP Servlet-Enabled JBoss Application Server: Installing, Configuring and Running”.

Differences Between the Standard Tomcat Installation and One Customized for the SIP Servlets Server

Provided here is a list of differences between a standard Tomcat Servlet Container installation and the SIP Servlets Server for Tomcat installation. The differences include:

  • The server.xml configuration file has been modified to provide extended classes to the standard Tomcat container classes, in order to allow SIP applications to be loaded and the SIP stack started.

  • A dars directory containing the default applications' router properties files for using the SIP Servlet Click-to-Call application (which comes bundled with the release) has been added to the conf directory.

  • Additional JAR files which can be found in the lib directory have been added to enable SIP Servlet functionality.

Installing the Java Development Kit

The Mobicents Platform is written in Java; therefore, before running any Mobicents server, you must have a working Java Runtime Environment (JRE) or Java Development Kit (JDK) installed on your system. In addition, the JRE or JDK you are using to run Mobicents must be version 5 or higher[3].

Should I Install the JRE or JDK?

Although you can run Mobicents servers using the Java Runtime Environment, we assume that most users are developers interested in developing Java-based, Mobicents-driven solutions. Therefore, in this guide we take the tact of showing how to install the full Java Development Kit.

Should I Install the 32-Bit or the 64-Bit JDK, and Does It Matter?

Briefly stated: if you are running on a 64-Bit Linux or Windows platform, you should consider installing and running the 64-bit JDK over the 32-bit one. Here are some heuristics for determining whether you would rather run the 64-bit Java Virtual Machine (JVM) over its 32-bit cousin for your application:

  • Wider datapath: the pipe between RAM and CPU is doubled, which improves the performance of memory-bound applications when using a 64-bit JVM.

  • 64-bit memory addressing gives virtually unlimited (1 exabyte) heap allocation. However large heaps affect garbage collection.

  • Applications that run with more than 1.5 GB of RAM (including free space for garbage collection optimization) should utilize the 64-bit JVM.

  • Applications that run on a 32-bit JVM and do not require more than minimal heap sizes will gain nothing from a 64-bit JVM. Barring memory issues, 64-bit hardware with the same relative clock speed and architecture is not likely to run Java applications faster than their 32-bit cousin.

Note that the following instructions detail how to download and install the 32-bit JDK, although the steps are nearly identical for installing the 64-bit version.

Downloading

You can download the Sun JDK 5.0 (Java 2 Development Kit) from Sun's website: http://java.sun.com/javase/downloads/index_jdk5.jsp. Click on the Download link next to "JDK 5.0 Update <x>" (where <x> is the latest minor version release number). On the next page, select your language and platform (both architecture—whether 32- or 64-bit—and operating system), read and agree to the Java Development Kit 5.0 License Agreement, and proceed to the download page.

The Sun website will present two download alternatives to you: one is an RPM inside a self-extracting file (for example, jdk-1_5_0_16-linux-i586-rpm.bin), and the other is merely a self-extracting file (e.g. jdk-1_5_0_16-linux-i586.bin). If you are installing the JDK on Red Hat Enterprise Linux, Fedora, or another RPM-based Linux system, we suggest that you download the self-extracting file containing the RPM package, which will set up and use the SysV service scripts in addition to installing the JDK. We also suggest installing the self-extracting RPM file if you will be running Mobicents in a production environment.

Installing

The following procedures detail how to install the Java Development Kit on both Linux and Windows.

Important

You do not need to install a -compat package in addition to the JDK if you installed the self-extracting RPM file! The -compat package merely performs the same SysV service script set up that the RPM version of the JDK installer does.

Configuring

Configuring your system for the JDK consists in two tasks: setting the JAVA_HOME environment variable, and ensuring that the system is using the proper JDK (or JRE) using the alternatives command. Setting JAVA_HOME usually overrides the values for java, javac and java_sdk_1.5.0 in alternatives, but we will set them all just to be safe and consistent.

Setting the JAVA_HOME Environment Variable on Generic Linux

After installing the JDK, you must ensure that the JAVA_HOME environment variable exists and points to the location of your JDK installation.

Setting the JAVA_HOME Environment Variable on Linux

You can determine whether JAVA_HOME is set on your system by echoing it on the command line:

~]$ echo $JAVA_HOME

If JAVA_HOME is not set already, then you must set its value to the location of the JDK installation on your system. You can do this by adding two lines to your personal ~/.bashrc configuration file. Open ~/.bashrc (or create it if it doesn't exist) and add a line similar to the following one anywhere inside the file:

export JAVA_HOME="/usr/lib/jvm/jdk1.5.0_<version>"

You should also set this environment variable for any other users who will be running Mobicents (any environment variables exported from ~/.bashrc files are local to that user).

Setting java, javac and java_sdk_1.5.0 Using the alternatives command
Selecting the Correct System JVM on Linux using alternatives

On systems with the alternatives command, including Red Hat Enterprise Linux and Fedora, you can easily choose which JDK (or JRE) installation you wish to use, as well as which java and javac executables should be run when called.

As the root user, call /usr/sbin/alternatives with the --config java option to select between JDKs and JREs installed on your system:

root@localhost ~]$ /usr/sbin/alternatives --config java

There are 3 programs which provide 'java'.

  Selection    Command
-----------------------------------------------
   1           /usr/lib/jvm/jre-1.5.0-gcj/bin/java
   2           /usr/lib/jvm/jre-1.6.0-sun/bin/java
*+ 3         /usr/lib/jvm/jre-1.5.0-sun/bin/java


Enter to keep the current selection[+], or type selection number:

In our case, we want to use the Sun JDK, version 5, that we downloaded and installed, to run the java executable. In the alternatives information printout above, a plus (+) next to a number indicates the one currently being used. As per alternatives' instructions, pressing Enter will simply keep the current JVM, or you can enter the number corresponding to the JVM you would prefer to use.

Repeat the procedure above for the javac command and the java_sdk_1.5.0 environment variable, as the root user:

~]$ /usr/sbin/alternatives --config javac
~]$ /usr/sbin/alternatives --config java_sdk_1.5.0
Setting the JAVA_HOME Environment Variable on Windows

For information on how to set environment variables in Windows, refer to http://support.microsoft.com/kb/931715.

Testing

Finally, to make sure that you are using the correct JDK or Java version (5 or higher), and that the java executable is in your PATH, run the java -version command in the terminal from your home directory:

~]$ java -version
java version "1.5.0_16"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_16-b03)
Java HotSpot(TM) Client VM (build 1.5.0_16-b03, mixed mode, sharing)
Uninstalling

There is usually no reason (other than space concerns) to remove a particular JDK from your system, given that you can switch between JDKs and JREs easily using alternatives, and/or by setting JAVA_HOME.

Uninstalling the JDK on Linux

On RPM-based systems, you can uninstall the JDK using the yum remove <jdk_rpm_name> command.

Uninstalling the JDK on Windows

On Windows systems, check the JDK entry in the Start menu for an uninstall command, or use Add/Remove Programs.

You can download the latest version of MSS for Tomcat from http://www.mobicents.org/mss-downloads.html. The top row of the table holds the latest version. Note that each release of the Mobicents SIP Servlets Server is comprised of two separate binary distribution files: one which is MSS for JBoss, and the other which is MSS for Tomcat. Download Mobicents SIP Servlets Server for Tomcat and continue with the following instructions.

Once the requirements and prerequisites have been met and you have downloaded the binary distribution zip file, you are ready to install MSS for Tomcat. Follow the instructions below for your platform, whether Linux or Windows.

Procedure 2.13. Installing the MSS for Tomcat Binary Distribution on Linux

  1. For this example, we'll assume you're currently in your home directory, which is where you downloaded the zip file to. First, create a subdirectory to hold the unzipped MSS for Tomcat files. It is good practice to include the version number in this directory name; if you do so, remember to correctly match it with the version of the MSS for Tomcat distribution you downloaded.

    ~]$ cd downloads
  2. In downloads, create a subdirectory to hold the unzipped MSS for Tomcat files. It is good practice to include the version number in this directory name; if you do so, remember to correctly match it with the version of the MSS for Tomcat binary distribution you downloaded.

    ~]$ mkdir "mss-tomcat-<version>"
  3. Move the downloaded zip file into the directory you have just created:

    ~]$ mv "mss-1.0.GA-apache-tomcat-6.0.14-0904221257.zip" "mss-tomcat-<version>"
  4. Move into that directory:

    ~]$ cd "mss-tomcat-<version>"
  5. Finally, use Java's jar -xvf command to extract the contents of the zip file into the current directory, thus completing the install:

    mss-tomcat-<version>]$ jar -xvf "mss-1.0.GA-apache-tomcat-6.0.14-0904221257.zip"
    • Alternatively, if Linux's unzip utility is present on your system or is installable, you can use it in lieu of Java's jar -xvf command:

      mss-tomcat-<version>]$ unzip "mss-1.0.GA-apache-tomcat-6.0.14-0904221257.zip"

      Note

      You can also use unzip's -d <unzip_to_location> option to extract the zip file's contents to a location other than the current directory.

  6. To free disk space, you may want to delete the zip file once you've extracted its contents:

    mss-tomcat-<version>]$ rm "mss-1.0.GA-apache-tomcat-6.0.14-0904221257.zip"

Procedure 2.14. Installing the MSS for Tomcat Binary Distribution on Windows

  1. For this example, we'll assume that you downloaded the binary distribution zip file to the My Downloads folder. First, using Windows Explorer, create a subdirectory in My Downloads to extract the zip file's contents into. When you name this folder, it is good practice to include the version number; if you do so, remember to correctly match it with the version of the MSS for Tomcat binary distribution you downloaded. In these instructions, we will refer to this folder as mss-tomcat-<version>.

  2. Double-click the downloaded zip file, selecting as the destination folder the one you just created to hold the zip file's contents.

  3. At this point, you may want to move the folder holding the MSS for Tomcat binary files (in this example, the folder named mss-tomcat-<version>) to another location. This step is not strictly necessary, but it is probably a good idea to move the installation folder from My Downloads to a user-defined location for storing runnable programs. Any location will suffice, however.

  4. You may want to delete the zip file after extracting its contents in order to free disk space:

    C:\Users\Me\My Downloads\mss-tomcat-<version>>delete "mss-1.0.GA-apache-tomcat-6.0.14-0904221257.zip"

Before running the Mobicents server you are installing, you should consider if you need to set the CATALINA_HOME environment variable. Setting it (or re-setting it) will always work. Whether or not you need to set CATALINA_HOME depends on the following factors:

The following instructions detail how to set CATALINA_HOME on both Linux and Windows.

Procedure 2.15. Setting the CATALINA_HOME Environment Variable on Linux

  1. The CATALINA_HOME environment variable must point to the location of your Tomcat installation. Any Mobicents server which runs on top of the Tomcat servlet container has a topmost directory, i.e. the directory in which you unzipped the zip file to install the server, and underneath that directory, a bin directory. CATALINA_HOME must be set to the topmost directory of your Mobicents server installation.

    Setting this variable in your personal ~/.bashrc file has the advantage that it will always be set (for you, as a user) each time you log in or reboot the system. To do so, open ~/.bashrc in a text editor (or create the file if it doesn't already exist) and insert the following line anywhere in the file, taking care to substitute <mobicents_server> for the topmost directory of the Mobicents server you installed:

    export CATALINA_HOME="/home/<username>/<path>/<to>/<mobicents_server>"

    Save and close .bashrc.

  2. You can—and should—source your .bashrc file to make your change take effect (so that CATALINA_HOME is set) for the current session:

    ~]$ source ~/.bashrc
  3. Finally, make sure that CATALINA_HOME has been set correctly (that it leads to the right directory), and has taken effect in the current session.

    The following command will show the path to the directory pointed to by CATALINA_HOME:

    ~]$ echo $CATALINA_HOME

    To be absolutely sure, change your directory to the one pointed to by CATALINA_HOME:

    ~]$ cd $CATALINA_HOME && pwd

Once installed, you can run the Tomcat Servlet Container by executing the one of the startup scripts in the bin directory (on Linux or Windows), or by double-clicking the run.bat executable batch file in that same directory (on Windows only). However, we suggest always starting Tomcat using the terminal or Command Prompt because you are then able to read—and act upon—any startup messages, and possibly debug any problems that may arise. In the Linux terminal or Command Prompt, you will be able to tell that the container started successfully if the last line of output is similar to the following:

Using CATALINA_BASE:   /home/silas/temp/apps/mobicents/sip_servlets_server/mss-tomcat-1.0
Using CATALINA_HOME:   /home/silas/temp/apps/mobicents/sip_servlets_server/mss-tomcat-1.0
Using CATALINA_TMPDIR: /home/silas/temp/apps/mobicents/sip_servlets_server/mss-tomcat-1.0/temp
Using JRE_HOME:       /etc/java-config-2/current-system-vm

Detailed instructions are given below, arranged by platform.

Detailed instructions for stopping the Tomcat Servlet Container are given below, arranged by platform. Note that if you properly stop the server, you will see the following three lines as the last output in the Linux terminal or Command Prompt (both running and stopping the Tomcat Servlet Container produces the same output):

Using CATALINA_BASE:   /home/silas/temp/apps/mobicents/sip_servlets_server/mss-tomcat-1.0
Using CATALINA_HOME:   /home/silas/temp/apps/mobicents/sip_servlets_server/mss-tomcat-1.0
Using CATALINA_TMPDIR: /home/silas/temp/apps/mobicents/sip_servlets_server/mss-tomcat-1.0/temp
Using JRE_HOME:       /etc/java-config-2/current-system-vm

SIP Connectors are added in the same way as HTTP Connectors: by adding a <Connector> element under the <Service> element in the container's server.xml configuration file.

Mobicents SIP Servlets has three SIP Connectors configured by default : UDP And TCP are running on the binding IP Address of the container and port 5080 and TLS is running on the binding IP Address of the container and port 5081

For example, to add a SIP Connector on the IP address 127.0.0.1, on port 5080, using the UDP transport protocol, you should insert the following XML element:


SIP <connector> Attributes

port

The port number on which the container will be able to receive SIP messages.

ipAddress

The IP address at which the container will be able to receive SIP messages. The container can be configured to listen to all available IP addresses by setting ipAddress to 0.0.0.0 <sipPathName>.

protocol

Specifies the connector is a SIP Connector and not an HTTP Connector. There is no need to change this property.

signalingTransport

Specifies the transport on which the container will be able to receive SIP messages. For example, "udp".

usePrettyEncoding

Allows Via, Route, and RecordRoute header field information to be split into multiple lines, rather than each header field being separating with a comma. The attribute defaults to "true". Leaving this attribute at the default setting may assist in debugging non-RFC3261 compliant SIP servers.

useStun

Enables Session Traversal Utilities for NAT (STUN) support for this Connector. The attribute defaults to "false". If set to "true", ensure that the ipAddress attribute is not set to 127.0.0.1. Refer to Section 7.4, “STUN Support” for more information about STUN.

stunServerAddress

Specifies the STUN server address used to discover the public IP address of the SIP Connector. This attribute is only required if the useStun attribute is set to "true". Refer to Section 7.4, “STUN Support” for more information about STUN and public STUN servers.

stunServerPort

Specifies the STUN server port of the STUN server used in the stunServerAddress attribute. You should rarely need to change this attribute; also, it is only needed if the useStun attribute is set to "true". Refer to Section 7.4, “STUN Support” for more information about STUN.

addressResolverClass

Specifies the gov.nist.core.net.AddressResolver implementation class that will be used by the container to perform DNS lookups. The default class used by the container is org.mobicents.servlet.sip.core.DNSAddressResolver but any class implementing gov.nist.core.net.AddressResolver NIST SIP Stack interface and having a Constructor with a org.mobicents.servlet.sip.core.SipApplicationDispatcher param can be used. To disable DNS lookups, this attribute should be left empty..

sipStackPropertiesFile

Specifies the location of the file containing key-value pairs corresponding to the SIP stack configuration properties. This attribute is used to further tune the JAIN SIP Stack. If this property is omitted, the following default values are assumed:

  • gov.nist.javax.sip.LOG_MESSAGE_CONTENT=true

  • gov.nist.javax.sip.TRACE_LEVEL=32

  • gov.nist.javax.sip.DEBUG_LOG=logs/mss-jsip-debuglog.txt

  • gov.nist.javax.sip.SERVER_LOG=logs/mss-jsip-messages.xml

  • javax.sip.STACK_NAME=Mobicents-SIP-Servlets

  • javax.sip.AUTOMATIC_DIALOG_SUPPORT=off

  • gov.nist.javax.sip.DELIVER_UNSOLICITED_NOTIFY=true

  • gov.nist.javax.sip.THREAD_POOL_SIZE=64

  • gov.nist.javax.sip.REENTRANT_LISTENER=true

Mobicents SIP Servlets also adds its own properties to allow for even more configuration and flexibility :

  • If the property org.mobicents.servlet.sip.SERVER_HEADER is set, A Server header will be added to all SIP Responses leaving the container.

  • If the property org.mobicents.servlet.sip.USER_AGENT_HEADER is set, A Server header will be added to all SIP Requests leaving the container.

useStaticAddress

Specifies whether the settings in staticServerAddress and staticServerPort are activated. The default value is "false" (deactivated).

staticServerAddress

Specifies what load-balancer server address is insterted in Contact/Via headers for server-created requests. This parameter is useful for cluster configurations where requests should be bound to a load-balancer address, rather than a specific node address.

staticServerPort

Specifies the port of the load-balancer specified in staticServerAddress . This parameter is useful in cluster configurations where requests should be bound to a load-balancer address rather than a specific node address.

Note

A comprehensive list of implementing classes for the SIP Stack is available from the Interface Sip Stack page on nist.gov. For a comprehensive list of properties associated with the SIP Stack implementation, refer to Class SipStackImpl page on nist.gov.

The application router is called by the container—whether JBoss or Tomcat—to select a SIP Servlet application to service an initial request. It embodies the logic used to choose which applications to invoke. An application router is required for a container to function, but it is a separate logical entity from the container. The application router is solely responsible for application selection and must not implement application logic. For example, the application router cannot modify a request or send a response.

For more information about the application router, refer to the following sections of the JSR 289 specification: Application Router Packaging and Deployment, Application Selection Process, and Appendix C.

In order to configure the application router, you should edit the Service element in the container's server.xml configuration file:


Provided here is a description of the SIP Service element's attributes:

className

This attribute specifies that the servlet container is a converged (i.e. SIP + HTTP) servlet container. This attribute can also be used to handle load-balancing and failover.

sipApplicationDispatcherClassName

This attribute specifies the class name of the org.mobicents.servlet.sip.core.SipApplicationDispatcher implementation to use. The routing algorithm and application selection process is performed in that class.

darConfigurationFileLocation

The default application router file location. This is used by the default application router to determine the application selection logic. Refer to Appendix C of the JSR 289 specification for more details.

additionalParameterableHeaders

Comma-separated list of header names that are treated as Parameterable by the container. The specified headers are classed as valid, in addition to the standard Parameterable headers defined in the Sip Servlets 1.1 Specification.

Setting and getting parameters is allowed for the standard, and additional parameters. Parameters that are not specified in additionalParameterableHeaders will result in a ServletParseException error.

baseTimerInterval

Specifies the T1 Base Timer Interval, which allows the SIP Servlets Container to adjust its timers depending on network conditions. The default interval is 500 (milliseconds).

For more information about available timers, refer to RFC326 "Table of Timer Values"1, and the document contained in the 3GPP-IMS TS 24.229 v9.1.0 specification ZIP archive.

Most of the timers present in the tables depend on T1, except for T2, T4, and Timer D (for the client transactions). The underlying SIP Servlets JAIN SLEE stack places further conditions on T2, T4, and Timer D through baseTimerInterval.

dispatcherThreadPoolSize

The number of threads used for processing SIP messages inside the Sip Servlets container by the dispatcher. The default value is 4.



[1] At this point in time, it is possible to run most Mobicents servers, such as the JAIN SLEE Server, using a Java 6 JRE or JDK. Be aware, however, that presently the XML Document Management Server does not run on Java 6. We suggest checking the Mobicents web site, forums or discussion pages if you need to inquire about the status of running the XML Document Management Server with Java 6.

[2] Note that any other terminals which were opened prior to your having altered .bashrc will need to source ~/.bashrc as well should they require access to JBOSS_HOME.

[3] At this point in time, it is possible to run most Mobicents servers, such as the JAIN SLEE Server, using a Java 6 JRE or JDK. Be aware, however, that presently the XML Document Management Server does not run on Java 6. We suggest checking the Mobicents web site, forums or discussion pages if you need to inquire about the status of running the XML Document Management Server with Java 6.

Application Routing is performed within the Mobicents Sip Servlets container by the Default Application Router. The following sections describe the Default Application Router, and how other Application Router implementations compliant with the JSR 289 specification can be installed.

The Application Router is called by the container to select a SIP Servlet application to service an initial request. It embodies the logic used to choose which applications to invoke.

An Application Router is required for a container to function, but it is a separate logical entity from the container. The Application Router is solely responsible for application selection and does not implement application logic. For example, the Application Router cannot modify a request or send a response.

There is no direct interaction between the Application Router and applications, only between the SIP Servlets Container and the Application Router.

The SIP Servlets container is responsible for passing the required information to the Application Router within the initial request so the Application Router can make informed routing decisions. Except for the information passed by the container, the Application Router is free to make use of any other information or data stores. It is up to the individual implementation how the Application Router makes use of the information or data stores.

The deployer in a SIP Servlet environment controls application composition by defining and deploying the Application Router implementation. Giving the deployer control over application composition is desirable because the deployer is solely responsible for the services available to subscribers.

Furthermore, the SIP Servlets specification intentionally allows the Application Router implementation to consult arbitrary information or data stores. This is because the deployer maintains subscriber information and this information is often private and valuable.

Mobicents SIP Servlets provides an implementation of the Default Application Router (DAR) as defined in the SIP Servlets 1.1 specification, Appendix C.

The Default Application Router (DAR) obtains its operational parameters from a configuration text file that is modeled as a Java properties file. The configuration file contains the information needed by the Application Router to select which SIP Servlet application will handle an incoming initial request.

In the case of Mobicents SIP Servlets, it is also possible to configure the DAR through the server.xml configuration file (see Example 2.2, “Configuring the Service Element in the Container's server.xml” and Section 1.2, “Working with the SIP Servlets Management Console”).

The properties file has the following characteristics and requirements:

  • It must be made available to the DAR.

  • It must allow the contents and file structure to be accessible from a hierarchical URI supplied as a system property javax.servlet.sip.ar.dar.configuration.

  • It is first read by the container when it loads up and is refreshed each time an application is deployed and undeployed.

  • It has a simple format in which the name of the property is the SIP method and the value is a comma-separated string value for the SipApplicationRouterInfo object.

    INVITE: (sip-router-info-1), (sip-router-info-2)..
    SUBSCRIBE: (sip-router-info-3), (sip-router-info-4)..
    ALL: (sip-router-info-5), (sip-router-info-6)..

    Mobicents SIP Servlets defines a new keyword called ALL. The keyword allows mapping between the sip-router-info data, and all methods supported by the container (for example, INVITE, REGISTER, SUBSCRIBE). This maping can save time when configuring an application that listens to all incoming methods.

Note

If ALL, and a specific method are defined in the DAR file, the specific method takes precedence over ALL. When the specific method no longer has applications to serve, ALL is enabled again.

The sip-router-info data specified in the properties file is a string value version of the SipApplicationRouterInfo object. It consists of the following information:

  • The name of the application as known to the container. The application name can be obtained from the <app-name> element of the sip.xml deployment descriptor of the application, or the @SipApplication annotation.

  • The identity of the subscriber that the DAR returns. The DAR can return any header in the SIP request using the DAR directive DAR:SIP_HEADER. For example, DAR:From would return the SIP URI in the From header. The DAR can alternatively return any string from the SIP request.

  • The routing region, which consists of one of the following strings: ORIGINATING, TERMINATING or NEUTRAL. This information is not currently used by the DAR to make routing decisions.

  • A SIP URI indicating the route as returned by the Application Router, which can be used to route the request externally. The value may be an empty string.

  • A route modifier, which consists of one of the following strings: ROUTE, ROUTE_BACK or NO_ROUTE. The route modifier is used in conjunction with the route information to route a request externally.

  • A string representing the order in which applications must be invoked (starts at 0). The string is removed later on in the routing process, and substituted with the order positions of sip-router-info data.

  • An optional string that contains Mobicents-specific parameters. Currently, only the DIRECTION and REGEX parameters are supported.

    .

    Note

    The field can contain unsupported key=value properties that may be supported in future releases. The unsupported properties will be ignored during parsing, until support for the attributes is provided.

    The syntax is demonstrated in Example 3.1, “DIRECTION Example”.

    • The DIRECTION parameter specifies whether an application serves external(INBOUND) requests or initiates (OUTBOUND) requests.

      If an application is marked DIRECTION=INBOUND, it will not be called for requests initiated by applications behaving as UAC. To mark an application as UAC, specify DIRECTION=INBOUND in the optinal parameters in the DAR.

      Applications that do not exist in the DAR list for the container are assumed to be OUTBOUND. Because undefined applications are incapable of serving external requests, they must have self-initiated the request. The Sip Servlets Management Console can be used to specify the DIRECTION parameter.

    • The REGEX parameter specifies a regular expression to be matched against the initial request passed to the Application Router.

      If the regular expression matches a part of the initial request, the application is called otherwise it is skipped.

      By example in the following sip-router-info data :

      INVITE: ("org.mobicents.servlet.sip.testsuite.SimpleApplication", "DAR:From", "ORIGINATING", "", "NO_ROUTE", "0", "REGEX=From:.*sip:.*@sip-servlets\.com")

      , only incoming initial requests having a From Header whose the SIP URI belongs to the sip-servlets.com domain will be passed to the SimpleApplication.



Initial Requests are those that can essentially be dialog creating (such as, INVITE, SUBSCRIBE and NOTIFY), and not part of an already existing dialog.

Initial requests are routed to applications deployed in the container according to the SIP Servlets 1.1 specification, Section 15.4.1 Procedure for Routing an Initial Request.

Example 3.3. INVITE Routing

The following example describes how the DAR routes an INVITE to two applications deployed in a container. The applications in this example are a Location Service and a Call Blocking application.

In the example, the assumption of a request coming to the server is described. However, applications can act as a UAC, and generate initial requests on their own. For routing purposes, it is not necessary for the specified application initiating the request to have an entry in the DAR file.

The DAR file contains the required information for the two applications to be invoked in the correct order.

INVITE: ("LocationService", "DAR:From", "ORIGINATING", "", "NO_ROUTE", "0"), ("CallBlocking", "DAR:To", "TERMINATING", "","NO_ROUTE", "1") 

Processing occurs in the following order:

  1. A new INVITE (not a re-INVITE) arrives at the container.

    The INVITE is a dialog creating request, and is not part of any dialog.

  2. The Application Router is called.

    From the INVITE information, the first application to invoke is the Location Service.

  3. The Application Router returns the application invocation order information to the container (along with the rest of the sip-router-info data) so the container knows which application to invoke.

  4. The container invokes the LocationService that proxies the INVITE.

    The proxied INVITE is considered as a new INVITE to the known IP Address of the registered user for the Request URI

    For further information regarding INVITE handling, refer to "Section 15.2.2 Sending an Initial Request" in the SIP Servlets 1.1 Specification.

  5. Because the INVITE has been proxied, the container invokes the Application Router for the proxied INVITE to see if any more applications are interested in the event.

  6. From the proxied invite, the Application Router determines that the second application to invoke is the Call Blocking application.

  7. The Application Router returns information regarding the Call Blocking application to the container (along with the rest of the sip-router-info data) so the container knows which application to invoke.

  8. The container routes the INVITE for the Call Blocking application to the next application in the chain.

  9. The Call Blocking application determines that the user that initiated the call is black listed. The application rejects the call with a "Forbidden" response.

  10. Because the Call Blocking application acts as a UAS, the Application Selection Process is stopped for the original INVITE.

The path the INVITE has taken (that is, LocationService to CallBlocking) is called the application path. The Routing of the responses will now occur as explained in the next section.


The SIP Servlet server has a selection of examples which demonstrate particular capabilities of the server. Table 4.1, “Available Examples” lists the available examples, their location, and a brief description about the functionality each example demonstrates. The examples can also provide a useful starting point for developing SIP Applications, therefore it is encouraged to experiment and adapt the base examples. Each example is available in both binary and source formats.

Table 4.1. Available Examples

ExampleDescription
Section 4.1.3, “The Call-Blocking Service” Demonstrates how to block calls by specifying that the INVITE SIP Extension checks the From address to see if it is specified in the block list. If the blocked SIP address matches, the Call Blocking application send a FORBIDDEN response.
Section 4.1.4, “The Call-Forwarding Service” Demonstrates how to forward calls by specifying that the INVITE SIP Extension checks the To address to see if it is specified in the forward list. If the SIP address matches, the application acts as a back-to-back user agent (B2BUA).
Section 4.1.5, “The Call-Controller Service” Call Blocking and Call Forwarding are merged to create a new service.
Speed Dial Demonstrates how to implement speed dialing for SIP addresses. The demonstration uses a static list of speed dial numbers. The numbers are translated into a complete address based on prior configuration. The SIP addresses are proxied without record-routing, or supervised mode.
Section 4.1.1, “The Location Service” Demonstrates a location service that performs a lookup based on the request URI, into a hard-coded list of addresses. The request is proxied to the set of destination addresses associated with that URI.
Composed Speed Dial and Location Speed Dial and Location are merged to create a new service. Speed Dial proxies the speed dial number to a SIP address, then Location Service proxies the call to the actual location of the call recipient.
Click to Call Demonstrates how SIP Servlets can be used along with HTTP servlets as a converged application to place calls from a web portal. The example is a modified version of the click to dial example from the Sailfin project, but has been reworked to comply with JSR 289.
Chat Server Demonstrates MESSAGE SIP Extension support. This example is based on the chatroom server demonstration from the BEA dev2dev project, and has been modified to meet JSR 289 requirements.
Media Demonstrates how the media playback SIP Servlet can build a media file customized with the name of the user, based on the information in the FROM header. This example is only compatible with JBoss AS. The solution is know to work with Ekiga and linphone SIP soft-phones.
Shopping Demonstrates integration with Seam and Java Enterprise Edition (JEE), and Media integration with text to speech (TTS) and dual-tone multi-frequency (DTMF) tones. The demonstration builds on the Converged Demo example, and adds support for the SIP Servlets v1.1 specification.
JSLEE/SIP Servlets Interoperability Demonstrates how the Mobicents platform components can work in concert with each other to provide a integrated solution. All major components of the platform are used in this example, which was created to demonstrate to JavaOne 2008 delegates a possible use case scenario for the platform.
Facebook Click to Call Demonstrates how SIP Servlets and HTTP Servlets can be used can be used to create a Facebook plug-in that allows user to call POTS phones through a SIP-PSTN gateway provider. This demonstration is only available from the source repository; no binary is available.
Section 4.1.2, “The Diameter Event-Changing Service” Demonstrates how the Diameter Event Charging, and the Location service, can be used to perform fixed-rated charging of calls (event charging). When a call is initiated, a debit of ten euros is applied to the A Party account. If the call is rejected by the B Party, or A Party hangs up before B Party can answer the call, the ten euro charge is credited to the A Party account.
Diameter Sh OpenIMS Integration Demonstrates the integration between Mobicents and OpenIMS, using the Diameter Sh interface to receive profile updates and SIP.
Conference Demonstrates the capabilities of the Media Server, such as endpoint composition and conferencing, as well as proving that SIP Servlets are capable of working seamlessly with any third-party web framework, without repackaging or modifying the deployment descriptors. The demonstration uses Google's GWT Ajax framework with server-push updates to provide a desktop-like user interface experience.
Media IPBX Demonstrates how a SIP PBX solution can be deployed using the Mobicents platform. For more information, refer to Section 4.1.6, “Media IPBX”.
JRuby on Rails SIP Servlets Demonstrates how JRuby on Rails can be used by the Mobicents platform to provide a multi-language application that can initiate phone calls to customers after they log a complaint through a web portal.
Pure JRuby on Rails Telco Builds on the JRuby on Rails SIP Servlets demonstration, but adds the ability to call the application rather that initially interact through the web portal. The application has the ability to set up and tear down the call.

The Mobicents Location Service contains a list of mappings of request URIs to destination addresses. When the Location Service receives a request, it performs a lookup on that mapping and proxies the request simultaneously to the destination address (or addresses) associated with that URI.

Regardless of whether you are using the JBoss Application Server or the Tomcat Servlet Container as the Servlets Server, the application, container and Location Service perform the following steps:

Here is the current list of hard-coded contacts and their location URIs:

 

Pre-Install Requirements and Prerequisites

The following requirements must be met before installation can begin.

Downloading

The Location Service is comprised of two archive files, a Web Archive (WAR) and a Default Application Router (DAR) configuration file, which you need to add to your installed SIP Servlets Server. For more information about WAR files, refer to the JBoss Application Server Administration and Development Guide. For more information about DAR files, refer to the JSR 289 spec, Appendix C.

Download the Location Service's WAR file from here: http://repository.jboss.org/maven2/org/mobicents/servlet/sip/example/location-service/1.4/location-service-1.4.war.

Download the Location Service's DAR file from here: http://www.mobicents.org/locationservice-dar.properties.

Installing

Both the location-service-1.4.war WAR file and the locationservice-dar.properties DAR file that you downloaded should be placed into different directories in your SIP Servlet Server installation hierarchy. Which directory depends on whether you are using the Location Service with MSS for JBoss or with MSS for Tomcat:

Configuring

The darConfigurationFileLocation attribute of the Service element must be set to the value conf/dars/locationservice-dar.properties. The instructions are given below by SIP Servlets Server type:

Running

Once the WAR and DAR files have been placed in the right directories, and the JBoss Application Server or Tomcat Servlet Container knows where to find them (which you specified in a server.xml file), then you should go ahead and run SIP Servlets Server.

To learn how to run the SIP Servlets-enabled JBoss Application Server, refer to Section 2.1.7, “Running”.

To learn how to run the SIP Servlets-enabled Tomcat Container, refer to Section 2.2.7, “Running”.

Testing

The following procedure shows how to test the Location Service.

Stopping

To learn how to stop the SIP Servlets-enabled JBoss Application Server, refer to Section 2.1.10, “Stopping”.

To learn how to stop the SIP Servlets-enabled Tomcat Container, refer to Section 2.2.8, “Stopping”.

Uninstalling

Unless disk space is at a premium, there is usually no need to uninstall the Location Service. However, if you will not be using it again, you may want to unset or reset the darConfigurationFileLocation attribute of the Service element, which you set in the server.xml configuration file in Configuring.

You may also wish to delete the WAR and DAR files for the Location Service, which you installed in Installing.

The Diameter Event-Changing Service is based on the Location Service, which performs call-charging at a fixed rate. Upon the initiation of a call, a debit of €10.00 occurs. In the cases of a call being rejected or the caller disconnecting (hanging up) before an answer is received, the caller's account is refunded.

Note that an MSS for JBoss installation is required to run this example; it will not work with MSS for Tomcat.

Provided here is a step-by-step description of the procedure as performed by the application and container:

Preparing your MSS for JBoss server to run the Diameter Event-Changing example requires downloading a WAR archive, a DAR archive, the Ericsson Charging Emulator, setting an attribute in JBoss's server.xml configuration file, and then running JBoss AS. Detailed instructions follow.

Pre-Install Requirements and Prerequisites

The following requirements must be met before installation can begin.

Downloading

The following procedure describes how to download the required files.

Installing

The following procedure describes how to install the downloaded files.

Configuring

To configure the server for the Event-Changing example, simply open the server.xml configuration file in your server's $JBOSS_HOME/server/<profile>/deploy/jboss-web.deployer/ directory, and edit the value of the darConfigurationFileLocation attribute of the Service element so that it is conf/dars/mobicents-dar.properties.


Running

The following procedure describes how to run the Diameter Event-Changing Service.

Procedure 4.3. Diameter Event-Changing Service

  1. First, you should run your MSS for JBoss server. For instructions on doing so, refer to Section 2.1.7, “Running”.

  2. Then, run the Ericsson Charging Emulator. Open a terminal, change the working directory to the location of the unzipped Charging Emulator files (in ChargingSDK-1_0_D31E or a similarly-named directory), and run it with the java -jar PPSDiamEmul.jar command:

    ~]$ java -jar PPSDiamEmul.jar

Using

Using the Event-Changing service means, firstly, inserting some parameters into the Charging Emulator, and then, by using two SIP (soft)phones, calling one with the other. The following sequential instructions show you how.

Procedure 4.4. Using the Diameter Event-Changing Service

  1. Configure the Ericsson SDK Charging Emulator

    Once you have started the Charging Emulator, you should configure it exactly as portrayed in Figure 4.1, “Configuring the Charging Emulator”.


    1. Set the Peer Id to: aaa://127.0.0.1:21812

    2. Set the Realm to: mobicents.org

    3. Set the Host IP to: 127.0.0.1

  2. Start two SIP (soft)phones. You should set the first phone up with the following parameters: sip:receiver@sip-servlets on IP address 127.0.0.1 on port 5090. The other phone can be set up any way you like.

  3. Before making a call, open the ConfigOptions dialog window, as shown in the image.

    In the Account Configuration window of the Charging Emulator, you can see the user's balances. Select a user to watch the balance. You can also stretch the window lengthwise to view the user's transaction history.

  4. Time to call! From the second, “any-configuration” phone, make a call to sip:receiver@sip-servlets.com. Upon doing so, the other phone should ring or signal that it is being contacted .

  5. You should be able to see a request—immediately following the invite and before the other party (i.e. you) accepts or rejects the call—sent to the Charging Emulator. That is when the debit of the user's account is made. In the case that the call is rejected, or the caller gives up, a second, new Diameter request is sent to refund the initial amount charged by the call. On the other hand, if the call is accepted, nothing else related to Diameter happens, and no second request takes place.

    Please not that this is not the truly-correct way to do charging, as Diameter provides other means, such as unit reservation. However, for the purpose of a demonstration it is sufficient to show the debit and follow-up credit working. Also, this is a fixed-price call, regardless of the duration. Charging can, of course, be configured so that it is time-based.

The Mobicents Call-Blocking Service, upon receiving an INVITE request, checks to see whether the sender's address is a blocked contact. If so, it returns a FORBIDDEN reply; otherwise, call setup proceeds as normal.

Here is the current hard-coded list of blocked contacts:

 

Pre-Install Requirements and Prerequisites

The following requirements must be met before installation can begin.

Downloading

The Call-Blocking Service is comprised of two archive files, a Web Archive (WAR) and a Default Application Router (DAR) configuration file, which you need to add to your installed SIP Servlets Server. For more information about WAR files, refer to the JBoss Application Server Administration and Development Guide. For more information about DAR files, refer to the JSR 289 spec, Appendix C.

Download the Call-Blocking Service's WAR file from here: http://repository.jboss.org/maven2/org/mobicents/servlet/sip/example/call-blocking/1.4/call-blocking-1.4.war.

Download the Call-Blocking Service's DAR file from here: http://www.mobicents.org/call-blocking-servlet-dar.properties.

Installing

Both the call-blocking-1.4.war WAR file and the call-blocking-servlet-dar.properties DAR file that you downloaded should be placed into different directories in your SIP Servlet Server installation hierarchy. Which directory depends on whether you are using the Call-Blocking Service with MSS for JBoss or with MSS for Tomcat:

Configuring

The darConfigurationFileLocation attribute of the Service element must be set to the value conf/dars/call-blocking-servlet-dar.properties. The instructions for doing so are given below by SIP Servlets Server type:

Running

Once the WAR and DAR files have been placed in the right directories, and the JBoss Application Server or Tomcat Servlet Container knows where to find them (which you specified in a server.xml file), then you should go ahead and run SIP Servlets Server.

To learn how to run the SIP Servlets-enabled JBoss Application Server, refer to Section 2.1.7, “Running”.

To learn how to run the SIP Servlets-enabled Tomcat Container, refer to Section 2.2.7, “Running”.

Testing

The following procedure shows how to test the Call-Blocking Service.

Stopping

To learn how to stop the SIP Servlets-enabled JBoss Application Server, refer to Section 2.1.10, “Stopping”.

To learn how to stop the SIP Servlets-enabled Tomcat Container, refer to Section 2.2.8, “Stopping”.

Uninstalling

Unless disk space is at a premium, there is usually no need to uninstall the Call-Blocking Service. However, if you will not be using it again, you may want to unset or reset the darConfigurationFileLocation attribute of the Service element, which you set in the server.xml configuration file in Configuring.

You may also wish to delete the WAR and DAR files for the Call-Blocking Service, which you installed in Installing.

The Mobicents Call-Forwarding Service, upon receiving an INVITE request, checks to see whether the sender's address is among those in a list of addresses which need to be forwarded. If so, then the Call-Forwarding Service acts as a Back-to-Back User Agent (B2BUA), and creates a new call leg to the destination. When the response is received from the new call leg, it sends it an acknowledgment (ACK) and then responds to the original caller. If, on the other hand, the server does not receive an ACK, then it tears down the new call leg with a BYE. Once the BYE is received, then it answers OK directly and sends the BYE to the new call leg.

Here is the current hard-coded list of contacts to forward:

 

Pre-Install Requirements and Prerequisites

The following requirements must be met before installation can begin.

Downloading

The Call-Forwarding Service is comprised of two archive files, a Web Archive (WAR) and a Data Archive (DAR), which you need to add to your installed SIP Servlets Server. For more information about WAR and DAR files, refer to the JBoss Application Server Administration and Development Guide.

Download the Call-Forwarding Service's WAR file from here: http://repository.jboss.org/maven2/org/mobicents/servlet/sip/example/call-forwarding/1.4/call-forwarding-1.4.war.

Download the Call-Forwarding Service's DAR file from here: http://www.mobicents.org/call-forwarding-servlet-dar.properties.

Installing

Both the call-forwarding-1.4.war WAR file and the call-forwarding-servlet-dar.properties DAR file that you downloaded should be placed into different directories in your SIP Servlet Server installation hierarchy. Which directory depends on whether you are using the Call-Forwarding Service with MSS for JBoss or with MSS for Tomcat:

Configuring

The darConfigurationFileLocation attribute of the Service element must be set to the value conf/dars/call-forwarding-b2bua-servlet-dar.properties. The instructions for doing so are given below by SIP Servlets Server type:

Running

Once the WAR and DAR files have been placed in the right directories, and the JBoss Application Server or Tomcat Servlet Container knows where to find them (which you specified in a server.xml file), then you should go ahead and run SIP Servlets Server.

To learn how to run the SIP Servlets-enabled JBoss Application Server, refer to Section 2.1.7, “Running”.

To learn how to run the SIP Servlets-enabled Tomcat Container, refer to bbssswticar-binary-SIP_Servlets_Server_with_Tomcat-Running.

Testing

The following procedure shows how to test the Call-Forwarding Service.

Stopping

To learn how to stop the SIP Servlets-enabled JBoss Application Server, refer to Section 2.1.10, “Stopping”.

To learn how to stop the SIP Servlets-enabled Tomcat Container, refer to Section 2.2.8, “Stopping”.

Uninstalling

Unless disk space is at a premium, there is usually no need to uninstall the Call-Forwarding Service. However, if you will not be using it again, you may want to unset or reset the darConfigurationFileLocation attribute of the Service element, which you set in the server.xml configuration file in Configuring.

You may also wish to delete the WAR and DAR files for the Call-Forwarding Service, which you installed in Installing.

The Call-Controller service is a composition of two other services: Call-Blocking and Call-Forwarding. Essentially, it performs the services of both call-forwarding and call-blocking.

The Call-Controller service requires the two WAR files for the Call-Blocking and Call-Forwarding services to be placed in the correct directory inside your Mobicents SIP Servlets Server binary installation. However, the Call-Controller service does not require their corresponding DAR files: you need only to download and install a DAR file customized for the Call-Controller service. The instructions below show you how to do precisely this; there is no need, therefore, to first install either the Call-Blocking or the Call-Forwarding services, though it is helpful to at least be familiar with them.

Pre-Install Requirements and Prerequisites

The following requirements must be met before installation can begin.

Downloading

The Call-Controller Service is comprised of two WAR files, one for the Call-Forwarding service and one for Call-Blocking, and a customized Call-Controller DAR file. You do not need to install the DAR files for the Call-Forwarding or the Call-Blocking services. For more information about WAR files, refer to the JBoss Application Server Administration and Development Guide. For more information about DAR files, refer to the JSR 289 spec, Appendix C

Download the Call-Blocking Service's WAR file from here: http://repository.jboss.org/maven2/org/mobicents/servlet/sip/example/call-blocking/1.4/call-blocking-1.4.war.

Download the Call-Forwarding Service's WAR file from here: http://repository.jboss.org/maven2/org/mobicents/servlet/sip/example/call-forwarding/1.4/call-forwarding-1.4.war.

Download the Call-Controller Service's DAR file from here: http://www.mobicents.org/call-controller-servlet-dar.properties.

Installing

The call-blocking-1.4.war, call-forwarding-1.4.war and call-controller-servlet-dar.properties archive files that you downloaded should be placed into different directories in your SIP Servlet Server installation hierarchy. Which directory depends on whether you are using the Call-Controller Service with MSS for JBoss or with MSS for Tomcat:

Configuring

The darConfigurationFileLocation attribute of the Service element must be set to the value conf/dars/call-controller-servlet-dar.properties. Instructions for doing so are given below by SIP Servlets Server type:

Running

Once the WAR and DAR files have been placed in the right directories, and the JBoss Application Server or Tomcat Servlet Container knows where to find them (which you specified in a server.xml file), then you should go ahead and run SIP Servlets Server.

To learn how to run the SIP Servlets-enabled JBoss Application Server, refer to Section 2.1.7, “Running”.

To learn how to run the SIP Servlets-enabled Tomcat Container, refer to Section 2.2.7, “Running”.

Testing

Two use-cases can be distinguished for the Call-Controller service: one in which a call is blocked, and another in which a call is forwarded. Therefore, we have two cases for which we can test the Call-Controller.

Stopping

To learn how to stop the SIP Servlets-enabled JBoss Application Server, refer to Section 2.1.10, “Stopping”.

To learn how to stop the SIP Servlets-enabled Tomcat Container, refer to Section 2.2.8, “Stopping”.

Uninstalling

Unless disk space is at a premium, there is usually no need to uninstall the Call-Controller Service. However, if you will not be using it again, you may want to unset or reset the darConfigurationFileLocation attribute of the Service element, which you set in the server.xml configuration file in Configuring.

You may also wish to delete the WAR and DAR files for the Call-Controller Service, which you installed in Installing.

Note

Chapter 4, SIP Servlet Example Applications provides more information about other service examples available.

The Media IPBX provides an extensible and customizable SIP PBX solution, based on the Seam Telco Framework (STF). While the PBX is currently provided as a capability demonstration, the ultimate goal is to transition Media IPBX into a fully-fledged SIP PBX solution.

Media IPBX terminates all calls to Mobicents Media Server conference endpoints, which provides flexibility in manipulating established calls including server-side conferencing and ring-back tones. The PBX can also be implemented as a Session Border Controller.

Media IPBX provides the following major features:

Many of the features in Media IPBX are presented to the user as hints on the GUI portal pages. It is recommended to install Media IPBX and experiment with the demonstration to gain an understanding of how the solution works.

For information about installing and running Media IPBX, including binary and source code locations, visit the Media IPBX homepage.

Mobicents supports the clustering of SIP Servlets-enabled JBoss Application Servers for performance, reliability and failover purposes. Note that only MSS for JBoss Servers can be used as cluster nodes; MSS for Tomcat Containers are not supported.

The SIP Servlets Server uses the JBoss Application Server as its servlet container, and takes advantage of its capabilities, including clustering and failover. For detailed background information about JBoss Application Server clustering refer to the JBoss Application Server Clustering Guide.

Software Prerequisites

A SIP Servlets-enabled JBoss Application Server

Before proceeding, ensure you have correctly configured your JBoss Application Server, according to SIP Servlet Server requirements:

The easiest way to set up a cluster of SIP Servlets-enabled JBoss Application Servers is to install, configure and test the binary distribution on one machine, and then copy the entire installation (directory) to the other machines in the cluster. This is the approach taken in this chapter.

Install a SIP Servlets Server with JBoss by following the instructions detailed in Section 2.1, “SIP Servlet-Enabled JBoss Application Server: Installing, Configuring and Running”.

Afer meeting the requirement you can begin to configure the server Section 5.1.1.2, “Configuring” below.

Once installed, the MSS for JBoss binary distribution requires only minor configuration in order to enable clustering.

SIP, and HTTP session state clustering is pre-configured straight out of the binary distribution. However, to enable session replication in a node, you must tag it as <distributable/> in the web.xml descriptor. This can be done either individually per application or globally for all applications.

To change the correct profile, open the web.xml configuration file, which is stored in the <install_directory>/server/all/deploy/jboss-web.deployer/conf/ directory,

Add the empty element <distributable/> as a child of the root element <web-app>.

This one configuration change is sufficient for enabling clustering capabilities in MSS for JBoss servers for all applications. For further information on session replication and clustering with JBoss, refer to Enabling session replication in your application in the JBoss Application Server Getting Started Guide.

Example 5.1. Enabling Node Session Replication in the Default web.xml Descriptor


<?xml version="1.0" encoding="utf-8"?><?xml version="1.0" encoding="ISO-8859-1"?>
<web-app
 xmlns="http://java.sun.com/xml/ns/j2ee"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"
 version="2.4">
  <!-- ======================== Introduction ============================== -->
  <!-- This document defines default values for *all* web applications      -->
  <!-- loaded into this instance of Tomcat.  As each application is         -->
  <!-- deployed, this file is processed, followed by the                    -->
  <!-- "/WEB-INF/web.xml" deployment descriptor from your own               -->
  <!-- applications.                                                        -->
  <!--                                                                      -->
  <!-- WARNING:  Do not configure application-specific resources here!      -->
  <!-- They should go in the "/WEB-INF/web.xml" file in your application.   -->
  <!-- =========== Common Context Params ================================== -->
  <!-- JBossInjectionProvider provides resource injection for managed beans. -->
  <!-- See JSF 1.2 spec section 5.4 for details.                             -->
  <distributable/>
 <context-param>
  <param-name>com.sun.faces.injectionProvider</param-name>
  <param-value>org.jboss.web.jsf.integration.injection.JBossInjectionProvider</param-value>
 </context-param>

Clustering with MSS for JBoss nodes requires running all of the nodes using the "all" Server Configuration Profile, which is specified when you invoke run.sh or run.bat.

Running MSS for JBoss with the "all" Configuration Profile, on Linux

To run the server on Linux using the "all" Configuration Profile, start the server with the following command:

MSS-jboss-<version>]$ ./bin/run.sh -c all
Running MSS for JBoss with the "all" Configuration Profile, on Windows

To run the server on Windows using the "all" Configuration Profile, open the Command Prompt, change your folder to the topmost folder of your MSS for JBoss installation, and issue the following command:

C:Usersuser\<username>My DownloadsMSS-jboss-<version>>binrun.bat -c all
Distributing requests between nodes

Together with the application server nodes, it is advised to run a SIP load-balancer or an IP load-balancer. The IP load balancer will distribute the traffic evenly between the nodes. A load-balancer is a single entry-point to all nodes. All calls should be made through the load balancer if High Availability is required. For more information about load balancing, refer to Section 5.3.5, “Implementation of the Mobicents Load Balancer”.

By default, the servers are configured with one SIP load-balancer set to the IP address 127.0.0.1. This is specified in the balancers attribute in the server.xml configuration file as follows:


<Service name="jboss.web" 
      className="org.mobicents.servlet.sip.startup.failover.SipStandardBalancerNodeService"
  balancers="127.0.0.1"  
  sipApplicationDispatcherClassName="org.mobicents.servlet.sip.core.SipApplicationDispatcherImpl"
concurrencyControlMode="None" 
  darConfigurationFileLocation="conf/dars/mobicents-dar.properties">

Multiple load balancers can be specified and all of them will be updated on the health status of the node. The complete syntax for the balancers string is the following:


<Service name="jboss.web" 
      ...
  balancers="ipAddress1:sipPort1:rmiPort1;ipAddress2:sipPort2:rmiPort2;..3...4.."  
  ...>

If the RMI port is omitted port 2000 is assumed, and if the SIP port is omitted 5065 is assumed.

Warning

The SIP port specified in the balancers string for each balancer refers to the internal SIP port of the SIP balancer. That is because the internal port faces the cluster nodes directly. Requests coming through the internal port will go to the external port and vice versa. If you put the external port in the balancers string, then the SIP LB will assume that the requests comes from outside the cluster and it will route it back to some cluster node instead of routing it outside the cluster as expected. Always use the SIP internal port in the balancers string. Exception to this rule is when a single port is used for internal and external ports in the SIP load balancer. In that case the direction analysis is done based on Via headers and the requests are routed correctly without extra settings.

When multiple SIP load balancers are specified, the outgoing requests will always go through the first one, or an IP load balancer can be used and the requests will be distributed based on the IP balancer policy. To route the outgoing requests to a particular IP address (the IP load balancer address for example) the outboundProxy property can be used:


<Service name="jboss.web" 
      ...
  balancers="127.0.0.1:5060:2000;127.0.0.1:5160:2100"  
outboundProxy="127.0.0.1:5500"
  ...>

In this example configuration all outbound requests will go through 127.0.0.1:5500, while the node will perform the health checks against two SIP load balancers. If the 127.0.0.1:5500 machine is an IP load balancer it should be configured to spray the SIP load balancers and they will route the requests outside the cluster reliably.

The outboundProxy attribute overrides the default effect of specifying a SIP port for SIP load balancers in the balancers string.

A Mobicents SIP Servlets Server for JBoss cluster does not employ any standby nodes. Typically, therefore, proxies and registrars must share the user location table by using a database cluster.

The Mobicents SIP load balancer, which is a SIP Call ID-aware load balancer, is used as the intermediary. The SIP load balancer forwards stateful transaction requests to cluster nodes based on its provisioning algorithm. The SIP load balancer acts as an entry-point to the cluster and distributes the incoming requests between nodes. It is always advised to use a SIP load balancer or an IP load balancer in a cluster configuration.

The SIP Stack used by the Mobicents SIP Servlets for JBoss supports ESTABLISHED SIP DIALOG failover. This means that failover will occur only on established calls (SIP Dialogs which are in the CONFIRMED state as per RFC 3261) and calls that are in the process of being setup will not be failed over (SIP Dialogs which are in the EARLY state as per RFC 3261).

Testing a cluster

This choice of implementation has many benefits:


The Mobicents SIP load balancer is used to balance the load of SIP service requests and responses between nodes in a SIP Servlets Server cluster. Both MSS for JBoss and MSS for Tomcat servers can be used in conjunction with the SIP load balancer to increase the performance and availability of SIP services and applications.

In terms of functionality, the Mobicents SIP load balancer is a simple stateless proxy server that intelligently forwards SIP session requests and responses between User Agents (UAs) on a Wide Area Network (WAN), and SIP Servlets Server nodes, which are almost always located on a Local Area Network (LAN). All SIP requests and responses pass through the SIP load balancer.

All User Agents send SIP messages, such as INVITE and MESSAGE, to the same SIP URI (the IP address and port number of the SIP load balancer on the WAN). The load balancer then parses, alters, and forwards those messages to an available node in the cluster. If the message was sent as a part of an existing SIP session, it will be forwarded to the cluster node which processed that User Agent's original transaction request.

The SIP Servlets Server that receives the message acts upon it and sends a response back to the SIP load balancer. The SIP load balancer reparses, alters and forwards the message back to the original User Agent. This entire proxying and provisioning process is carried out independent of the User Agent, which is only concerned with the SIP service or application it is using.

By using the load balancer, SIP traffic is balanced across a pool of available SIP Servlets Servers, increasing the overall throughput of the SIP service or application running on either individual nodes of the cluster. In the case of MSS for JBoss's </distributed> capabilities, load balancing advantages are applied across the entire cluster.

The SIP load balancer is also able to fail over requests mid-call from unavailable nodes to available ones, thus increasing the reliability of the SIP service or application. The load balancer increases throughput and reliability by dynamically provisioning SIP service requests and responses across responsive nodes in a cluster. This enables SIP applications to meet the real-time demand for SIP services.

In addition to the SIP load balancing, there are several options for coordinated or cooperative load balancing with other protocols such as HTTP. Typically, a JBoss Application Server will use apache HTTP server with mod_jk, mod_proxy, mod_cluster or similar extension installed as an HTTP load balancer. This apache-based load balancer will parse incoming HTTP requests and it will look for the session ID of those requests in order to ensure all requests from the same session arrive at the same application server. By default, this is done by examining the jsessionid HTTP cookie or GET parameter and looking for the jvmRoute assigned to the session. The typical jsessionid value is of the form <sessionId>.<jvmRoute> (e.g. mysessionid323424.node1 where node1 is the jvmRoute component). The very first request for each new HTTP session do not have any session ID assigned, thus apache routes the request to a random application server node. When the node responds it assigns a session ID and jvmRoute to the response of the request in a HTTP cookie and this response goes back to the client through apache, which keeps track of which node owns which jvmRoute. Once, the very first request is served this way, the subsequent requests from this session will carry the assigned cookie and the apache load balancer will always route the requests to the node, which advertised itself as the jvmRoute owner.

Instead of using apache, an integrated HTTP load balancing is also available. The SIP load balancer has an HTTP port where you could direct all incoming HTTP requests. The integrated HTTP load balancer behaves exactly like apache by default, but this behaviour is extensible and can be overridden completely with the pluggable balancer algorithms. The integrated HTTP load balancer is much easier to configure and generally requires no effort, because it reuses most SIP settings ans assumes reasonable default values.

Unlike the native apache, the integrated HTTP load balancer is written completely in Java, thus a performance penalty should be expected when using it. However, the integrated HTTP balancer has an advantage when related SIP and HTTP requests must stick to the same node.

The SIP/HTTP load balancer exposes an interface to allow users to customize the routing decision making for special purposes. By default there are three built-in algorithms. Only one algorithm is active at any time and it is specified with the algorithmClass property in the configuration file.

It is completely up to the algorithm how and whether to support distributed architecture or how to store the information needed for session affinity. The algorithms will be called for every SIP and HTTP request and other significant events to make more informed decisions.

The following is a list o the built-in algorithms:

The Mobicents SIP load balancer appends itself to the Via header of each request, so that returned responses are sent to the SIP Balancer before they are sent to the originating endpoint.

The load balancer also adds itself to the path of subsequent requests by adding Record-Route headers. It can subsequently handle mid-call failover by forwarding requests to a different node in the cluster if the node that originally handled the request fails or becomes unavailable. The SIP load balancer immediately fails over if it receives and unhealthy status, or irregular heartbeats from a node.

The SIP Servlets Server extends the SipStandardService class, which extends the Tomcat StandardService class. The StandardService class is responsible for implementing the Tomcat Service interface.

In Tomcat architecture, a service is an intermediate component which resides inside a server, and binds one or more Connectors to exactly one Engine. When the service is started, the new SipStandardBalancerNodeService looks up its configuration information and obtains the SIP load balancer address. The heartbeat and health status is sent to the SIP load balancer address to identify the service as an available node of the cluster.

The node parameters are configurable through their MBean interfaces; information on their configuration is provided in the following sections.

In advanced configurations, it is possible to run more than one SIP load balancer.

Figure 5.3, “Basic IP and Port Cluster Configuration” describes a basic IP and Port Cluster Configuration. In the diagram, the SIP load balancer is the server with the IP address of 192.168.1.1.


Configuring the SIP load balancer and the two SIP Servlets-enabled Server nodes is described in Configuring the Mobicents SIP Load Balancer and Servlet Server Nodes.

Procedure 5.1. Configuring the Mobicents SIP Load Balancer and Servlet Server Nodes

  1. Configure lb.properties Configuration Properties File

    Configure the SIP load balancer's Configuration Properties file by substituting valid values for your personal setup. Example 5.2, “Complete Sample lb.properties File” shows a sample lb.properties file, with key element descriptions provided after the example. The lines beginning with the pound sign are comments.

    Example 5.2. Complete Sample lb.properties File

    # Mobicents Load Balancer Settings
    # For an overview of the Mobicents Load Balancer visit http://docs.google.com/present/view?id=dc5jp5vx_89cxdvtxcm
    
    # The binding address of the load balancer
    host=127.0.0.1
    
    # The RMI port used for heartbeat signals
    rmiRegistryPort=2000
    
    # The SIP port used where client should connect
    externalPort=5060
     
    # The SIP port from where servers will receive messages
    # delete if you want to use only one port for both inbound and outbound)
    # if you like to activate the integrated HTTP load balancer, this is the entry point
    internalPort=5065
     
    # The HTTP port for HTTP forwarding
    httpPort=2080
    
    #Specify UDP or TCP (for now both must be the same)
    internalTransport=UDP
    externalTransport=UDP
    
    # If you are using IP load balancer, put the IP address and port here
    #externalIpLoadBalancerAddress=127.0.0.1
    #externalIpLoadBalancerPort=111
     
    # Requests initited from the App Servers can route to this address (if you are using 2 IP load balancers for bidirectional SIP LB)
    #internalIpLoadBalancerAddress=127.0.0.1
    #internalIpLoadBalancerPort=111
    
    # Designate extra IP addresses as serer nodes
    #extraServerNodes=222.221.21.12:21,45.6.6.7:9003,33.5.6.7,33.9.9.2
    
    # Call-ID affinity algortihm settings. This algorithm is the default. No need to uncomment it.
    #algorithmClass=org.mobicents.tools.sip.balancer.CallIDAffinityBalancerAlgorithm
    # This property specifies how much time to keep an association before being evitcted.
    # It is needed to avoid memory leaks on dead calls. The time is in seconds.
    #callIdAffinityMaxTimeInCache=500
    
    # Uncomment to enable the consistent hash based on Call-ID algorithm.
    #algorithmClass=org.mobicents.tools.sip.balancer.HeaderConsistentHashBalancerAlgorithm
    # This property is not required, it defaults to Call-ID if not set, cna be "from.user" or "to.user" when you want the SIP URI username
    #sipHeaderAffinityKey=Call-ID
    #specify the GET HTTP parameter to be used as hash key
    #httpAffinityKey=appsession
     
    # Uncomment to enable the persistent consistent hash based on Call-ID algorithm.
    #algorithmClass=org.mobicents.tools.sip.balancer.PersistentConsistentHashBalancerAlgorithm
    # This property is not required, it defaults to Call-ID if not set
    #sipHeaderAffinityKey=Call-ID
    #specify the GET HTTP parameter to be used as hash key
    #httpAffinityKey=appsession
     
    #This is the JBoss Cache 3.1 configuration file (with jgroups), if not specified it will use default
    #persistentConsistentHashCacheConfiguration=/home/config.xml
     
    # Call-ID affinity algortihm settings. This algorithm is the default. No need to uncomment it.
    #algorithmClass=org.mobicents.tools.sip.balancer.CallIDAffinityBalancerAlgorithm
    # This property specifies how much time to keep an association before being evitcted.
    # It is needed to avoid memory leaks on dead calls. The time is in seconds.
    #callIdAffinityMaxTimeInCache=500
    
    # Uncomment to enable the consistent hash based on Call-ID algorithm.
    #algorithmClass=org.mobicents.tools.sip.balancer.HeaderConsistentHashBalancerAlgorithm
    # This property is not required, it defaults to Call-ID if not set, cna be "from.user" or "to.user" when you want the SIP URI username
    #sipHeaderAffinityKey=Call-ID
    #specify the GET HTTP parameter to be used as hash key
    #httpAffinityKey=appsession
    
    # Uncomment to enable the persistent consistent hash based on Call-ID algorithm.
    #algorithmClass=org.mobicents.tools.sip.balancer.PersistentConsistentHashBalancerAlgorithm
    # This property is not required, it defaults to Call-ID if not set
    #sipHeaderAffinityKey=Call-ID
    #specify the GET HTTP parameter to be used as hash key
    #httpAffinityKey=appsession
     
    #This is the JBoss Cache 3.1 configuration file (with jgroups), if not specified it will use default
    #persistentConsistentHashCacheConfiguration=/home/config.xml
    
    #Adjusting the heatbeat. The hearbeat must be specified together with the individual server JAIN SIP property org.mobicents.ha.javax.sip.HEARTBEAT_INTERVAL
    #If a node doesnt check in within that time (in ms), it is considered dead
    nodeTimeout=5100
    #The consistency of the above condition is checked every heartbeatInterval milliseconds
    heartbeatInterval=5000
    
    
    #JSIP stack configuration.....
    javax.sip.STACK_NAME = SipBalancerForwarder
    javax.sip.AUTOMATIC_DIALOG_SUPPORT = off
    // You need 16 for logging traces. 32 for debug + traces.
    // Your code will limp at 32 but it is best for debugging.
    gov.nist.javax.sip.TRACE_LEVEL = 32
    gov.nist.javax.sip.DEBUG_LOG = logs/sipbalancerforwarderdebug.txt
    gov.nist.javax.sip.SERVER_LOG = logs/sipbalancerforwarder.xml
    gov.nist.javax.sip.THREAD_POOL_SIZE = 64
    gov.nist.javax.sip.REENTRANT_LISTENER = true
    
                

    host

    Local IP address, or interface, on which the SIP load balancer will listen for incoming requests.

    externalPort

    Port on which the SIP load balancer listens for incoming requests from SIP User Agents.

    internalPort

    Port on which the SIP load balancer forwards incoming requests to available, and healthy, SIP Servlets Server cluster nodes.

    rmiRegistryPort

    Port on which the SIP load balancer will establish the RMI heartbeat connection to the application servers. When this connection fails or a disconnection instruction is received, an application server node is removed and handling of requests continues without it by redirecting the load to the lie nodes.

    httpPort

    Port on which the SIP load balancer will accept HTTP requests to be distributed across the nodes.

    internalTransport

    Transport protocol for the internal SIP connections associated with the internal SIP port of the load balancer. Possible choices are UDP, TCP and TLS.

    externalTransport

    Transport protocol for the external SIP connections associated with the external SIP port of the load balancer. Possible choices are UDP, TCP and TLS. It must match the transport of the internal port.

    externalIpLoadBalancerAddress

    Address of the IP load balancer (if any) used for incoming requests to be distributed in the direction of the application server nodes. This address may be used by the SIP load balancer to be put in SIP headers where the external address of the SIP load balancer is needed.

    externalIpLoadBalancerPort

    The port of the external IP load balancer. Any messages arriving at this port should be distributed across the external SIP ports of a set of SIP load balancers.

    internalIpLoadBalancerAddresst

    Address of the IP load balancer (if any) used for outgoing requests (requests initiated from the servers) to be distributed in the direction of the clients. This address may be used by the SIP load balancer to be put in SIP headers where the internal address of the SIP load balancer is needed.

    internalIpLoadBalancerPort

    The port of the internal IP load balancer. Any messages arriving at this port should be distributed across the internal SIP ports of a set of SIP load balancers.

    extraServerNodes

    Comma-separated list of hosts that are server nodes. You can put here alternative names of the application servers here and they will be recognized. Names are important, because they might be used for direction-analysis. Requests coming from these server will go in the direction of the clients and will not be routed back to the cluster.

    algorithmClass

    The fully-qualified Java class name of the balancing algorithm to be used. There are three algorithms to choose from and you can write your own to implement more complex routing behaviour. Refer to the sample configuration file for details about the available options for each algorithm. Each algorithm can have algorithm-specific properties for fine-grained configuration.

    nodeTimeout

    In milliseonds. Default value is 5100. If a server node doesnt check in within this time (in ms), it is considered dead.

    heartbeatInterval

    In milliseconds. Default value is 5000 milliseonds. The hearbeat interval must be the same or close to the interval specified in the JAIN SIP property on the server machines - org.mobicents.ha.javax.sip.HEARTBEAT_INTERVAL

  2. Configure the server.xml configuration file

    Ensure the following attributes are configured for the <service> element in server.xml.

    • The className attribute must have the value org.mobicents.servlet.sip.startup.failover.SipStandardBalancerNodeService instead of org.mobicents.servlet.sip.startup.SipStandardService.

    • The balancers attribute must contain a IP address (or list of addresses) of the SIP load balancer(s) to which heartbeat information will be sent.

    • The sipPathName attribute must contain the following value org.mobicents.ha to indicate that the server will be using the Mobicents JAIN SIP HA SIP Stack which is an extension of the JAIN SIP Stack offering transparent replication.

the SIP load balancer uses Java Logging as a logging mechanism. As such you cna configure it through a property file and specify the property file to be used by using the following command -Djava.util.logging.config.file=./lb-logging.properties. Please refer to JDK logging for more informationon how to configure the Java logging.

Configuration File Locations

On MSS for Tomcat server installations, server.xml is located in <install_directory>/conf.

On MSS for JBoss server installations, the default server.xml configuration file is located in server/default/deploy/jboss-web.deployer.

On MSS for JBoss installations, with JBoss clustering support enabled, the "all" server.xml file must be configured. It is located in server/all/deploy/jboss-web.deployer.

To determine what profile should be altered for each MSS for JBoss installation, refer to Section 5.1, “Mobicents SIP Servlets for JBoss: Clustering Support”.

Easy Node Configuration with JMX

Both SIP Servlet-enabled JBoss and Tomcat have JMX (Java Management Extensions) interfaces that allow for easy server configuration. The JMX Console is available once the server has been started by navigating to http://localhost:8080/jmx-console/.

Both the balancers and heartBeatInterval attribute values are available under serviceName=jboss.web,type=Service in the JMX Console.

balancers

Host names of the SIP load balancer(s) with corresponding addBalancerAddress and removeBalancerAddress methods.

heartBeatInterval

Interval at which each heartbeat is sent to the SIP load balancer(s).

Procedure 5.2. Running the SIP Load Balancer and Servlet Server Nodes

  1. Start the SIP Load Balancer

    Start the SIP load balancer, ensuring the Configuration Properties file (lb.properties in this example) is specified. In the Linux terminal, or using the Windows Command Prompt, the SIP Load Balancer is started by issuing a command similar to this one:

    java -jar sip-balancer-1.0-20080829.103906-21-jar-with-dependencies.jar lb-configuration.properties

    Executing the SIP load balancer produces output similar to the following example:

    home]$ java -jar sip-balancer-1.0-20080829.103906-21-jar-with-dependencies.jar lb-configuration.properties 
    Oct 21, 2008 1:10:58 AM org.mobicents.tools.sip.balancer.SIPBalancerForwarder start
    INFO: Sip Balancer started on address 127.0.0.1, external port : 5060, port : 5065
    Oct 21, 2008 1:10:59 AM org.mobicents.tools.sip.balancer.NodeRegisterImpl startServer
    INFO: Node registry starting...
    Oct 21, 2008 1:10:59 AM org.mobicents.tools.sip.balancer.NodeRegisterImpl startServer
    INFO: Node expiration task created
    Oct 21, 2008 1:10:59 AM org.mobicents.tools.sip.balancer.NodeRegisterImpl startServer
    INFO: Node registry started

    The output shows the IP address on which the SIP load balancer is listening, as well as the external and internal listener ports.

  2. Configure SIP Servlet Server Nodes

    SIP Servlets Server nodes can run on the JBoss Application Server, or the Tomcat Servlet Container. The SIP Servlets Server binary distributions define the type of SIP Servlets Server nodes used, and should already be installed from Software Prerequisites.

    The server.xml file specifies the nodes used. Because there is more then one client node specified, unique listener ports must be specified for each node to monitor HTTP and/or SIP connections. Example 5.3, “Changing the SIP Connector Port for Servlet Server Nodes in server.xml” describes the affected element in the server.xml file.

    Configuration File Location

    For the JBoss SIP Servlets Server binary distribution, server.xml is located in the <install_directory>/server/all/deploy/jboss-web.deployer/ directory. For the Tomcat binary distribution, server.xml is located in the <install_directory>/conf/ directory.


  3. Start Load Balancer Client Nodes

    Start all SIP load balancer client nodes.

Jopr is an enterprise management solution for JBoss middleware projects and other application technologies. This pluggable project provides administration, monitoring, alerting, operational control and configuration in an enterprise setting with fine-grained security and an advanced extension model.

It provides support for monitoring base operating system information on six operating systems as well as management of Apache, JBoss Application Server (JBoss AS) and other related projects. See the Jopr website for more information or see the Jopr embedded website

This chapter provides information on how to enable the management of Mobicents SIP Servlets Servers through Jopr with our custom Jopr plug in. Two versions of Jopr are available: an embedded version, which is better suited to development environments; and a full version, which is better suited to production environments.

The Mobicents SIP Servlet Jopr plug in provides a facility to view metrics related to the deployed applications, metrics related to the SIP Servlets Server. Additionally, the plugin provides the option to manage the various configuration settings of the SIP Servlets Server such as Congestion and Concurrency control.

This documentation provides information on how to enable the management of Mobicents SIP Load Balancer through Jopr with our custom SIP Load Balancer Jopr plug in.

With the Mobicents SIP Load Balancer Jopr plug in, you can currently see metrics, configure and manage the Mobicents SIP Load Balancer.

The advanced features of Mobicents SIP Servlets include Concurrency and Congestion Control, Load Balancing with the Mobicents Load Balancer, and, exclusively for MSS for JBoss, clustering and failover support.

Mobicents SIP Servlets by implementing the SIP Servlets 1.1 specification is providing natively support for applications to setup calls through SIP Support.

But since most Telco services have the need for managing and controlling media, by example to play announcements, mixing calls, recognize DTMF, ... Mobicents SIP Servlets allows applications to control media in 2 ways.

Since JSR 309 is not final yet, the Mobicents Media Server provides it's own client API so that any applications within Mobicents SIP Servlets can interact with the Mobicents Media Server. One limitation with this API is that you can only control the Media Server if it's located in the same JVM as the Mobicents SIP Servlets container.

The documentation of the API is provided in the Mobicents Media Server user guide

The following examples demonstrate its usage :

  • Media Example : a SIP Servlet application showing how to use media capabilities (Media playback, Text to Speech with FreeTTS and DTMF detection).

  • Conference Demo : a Conference Media Server demo application built on GWT with server-push updates.

  • Shopping Example : a Converged JEE Application showing SEAM integration, JEE, Media integration with TTS and DTMF support.

Concurrency and Congestion control refer to settings that define the way in which messages are processed under heavy load. The way Mobicents SIP Servlets Server processes messages in a production environment is crucial to ensure quality of service for customers.

Concurrency control mode tuning affects the way in which the SIP Servlets Server processes messages, whereas Congestion Control tuning affects the point at which the server begins rejecting new requests. Both of these parameters can be set using the following methods:

Concurrency Control

The JSR 289 expert group does not specify how concurrency control should be implemented.

Mobicents SIP Servlets for JBoss and Mobicents SIP Servlets for Tomcat have concurrency control implemented as a configurable mode, which defines the way in which the SIP Servlets Server processes messages. The following modes are provided, and cater for the particular setup required in an implementation:

None

All SIP messages are processed as soon as possible in a thread from the global thread pool.

When two messages belong to the same SipSession, they can be concurrently processed. Ensure that SIP Messages that access shared resources (such as the session attribute) concurrently are synchronized in a thread-safe manner.

Transaction

Bypass the SIP Servlets request/response executors, and utilize the JAIN SIP built-in Transaction serialization to manage race conditions on the same transaction.

By default, the SIP Servlets server uses a ThreadPoolExecutor linked to a LinkedBlockingQueue to dispatch the request/response threads. The container can thus handles two different response (for example a 180 Ringing and a 200 OK) concurrently, a race condition can occur where the second response overtakes the first one (200 OK dispatched to the application before the 180 Ringing).

SipSession

SIP messages are processed as soon as possible except for messages originating from the same SipSession. These messages are excluded from any simultaneous processing.

Messages from the same SipSession are processed sequentially, in the order they originally arrived.

Two (or more) messages from different SipSession instances in the same SipApplicationSession may be processed simultaneously. For this reason, ensure that SIP Messages which access shared resources (such as the session attribute) concurrently are synchronized in a thread-safe manner.

Thread-safety is particularly important in Back-to-Back User Agent (B2BUA) cases, where each communication leg of the B2BUA consists of a different SipSession in the same SipApplicationSession.

SipApplicationSession

SIP messages are processed as soon as possible, with the guarantee that no two messages from the same SipSession or from the same SipApplicationSession will ever be processed simultaneously. Of all the available methods, this mode is the best choice for guaranteed thread-safety.

If applications access shared resources in an unmanaged way (for example, by accessing a SipSession attribute from an unmanaged thread, or from an Enterprise JavaBean) access will not be synchronized.

Congestion Control

Mobicents Sip Servlets currently provides the following congestion control mechanisms :

A background task gathers information about the current server congestion. The data collection interval can be adjusted, and congestion control deactivated, by setting the interval to 0 or a negative value.

The congestion control policy defines how an incoming message is handled when the server is overloaded. The following parameters are configurable:

Configuring the Concurrency and Congestion Control Settings

The concurrency and congestion control settings can be configured through the SIP Servlets Management Console, using the following methods:

Tuning Parameters with the SIP Servlets Management Console

The easiest way to configure the SIP Message Queue Size and Concurrency Control Mode tunable parameters is to open the SIP Servlets Management Console in your browser (by going to http://localhost:8080/sip-servlets-management), making your changes, and then Applying them.


Persistent Settings

Concurrency and congestion control settings altered through the SIP Servlets Management console are not saved to the server.xml configuration file.

To make settings persistent, append the settings to the server.xml file directly.

Tuning Parameters Permanently by Editing server.xml

Alternatively, you can edit your server's server.xml configuration file, which has the benefit of making your chosen settings changes permanent. Instructions follow, grouped by the SIP Servlets Server you are running:

Procedure 7.1. Tuning Mobicents SIP Servlets for JBoss Server Settings for Concurrency and Congestion Control

  1. Open server.xml File

    Open the $JBOSS_HOME/server/default/deploy/jboss-web.deployer/server.xml configuration file in a text editor.

  2. Add Parameters to <service> Element

    Locate the <service> element, and add the concurrencyControlMode and/or sipMessageQueueSize attributes.


    Possible values for the concurrencyControlMode attribute include: None, SipSession or SipApplicationSession. SipSession is the value of this attribute when it is not present—and overridden—in server.xml.

  3. Define the Correct Attribute Values

    The following default values for the concurrency and congestion control parameters are used regardless of whether the attributes are defined in the server.xml file:

    Experimentation is required for these tuning parameters depending on the operating system and server.

Tuning Parameters from the dispatcher MBean

Navigate to the dispatcher MBean from Mobicents SIP Servlets for JBoss's JMX console.

All changes performed at run time are effective immediately, but do not persist across reboots. As with JBoss and Tomcat, the server.xml must be appended with the settings in order to make the configuration persistent.

When editing the dispatcher MBean from Mobicents SIP Servlets for JBoss's JMX console, values allowed for the concurrency control mode are None, SipSession or SipApplicationSession.

Tuning Parameters from Enterprise Monitoring and Managent Console

If the Enterprise Monitoring and Managenemt console is installed as described in Chapter 6, Enterprise Monitoring and Management, the tunable parameters can be altered by following the instructions in Section 6.1.2.1, “Jopr for Development” or Section 6.1.2.2, “Jopr For Production”

The information present in SIP requests often contains sensitive user information. To protect user information, SIP Security can be enabled on the server, and within the SIP application to mitigate the risk of unauthorised access to the information.

Application security varies depending on the server type used. The following procedures describe how to configure the JBoss Application Server, and the Tomcat server.

Procedure 7.3. Enable SIP Application Security in JBoss Application Server

  1. Add Security Policy to Server

    1. Open a terminal and navigate to the conf directory:

      home]$ cd server/default/conf/
    2. Open login-config.xml (using your preferred editor) and append the security policy to the file:

      
      
      <application-policy name="sip-servlets">
      <authentication>
        <login-module code="org.jboss.security.auth.spi.UsersRolesLoginModule" 
          flag = "required">
        <module-option name="usersProperties">props/sip-servlets-
          users.properties</module-option>
        <module-option name="rolesProperties">props/sip-servlets-
          roles.properties</module-option>
        <module-option name="hashAlgorithm">MD5</module-option>
        <module-option name="hashEncoding">rfc2617</module-option>
        <module-option name="hashUserPassword">false</module-option>
        <module-option name="hashStorePassword">true</module-option>
        <module-option name="passwordIsA1Hash">true</module-option>
        <module-option name="storeDigestCallback">
          org.jboss.security.auth.spi.RFC2617Digest</module-option>
        </login-module>
      </authentication>
      </application-policy>
        
  2. Update SIP Server User Properties File

    1. Open a terminal and navigate to the /props directory:

      home]$ cd server/default/props/
    2. Open sip-servlets-users.properties and append the user lines to the file:

       
        # A sample users.properties file, this line creates user "admin" with 
        # password "admin" for "sip-servlets-realm"
        admin=<A1_cryptographic_string>
        
    3. To create <A1_cryptographic_string>, execute the following command in a terminal:

      home]$ java -cp ../server/default/lib/jbosssx.jar
    4. Copy the A1 hash, and paste it into the admin parameter in the previous step.

    5. Save and close sip-servlets-users.properties.

  3. Update SIP Server Roles File

    1. Open a terminal and navigate to the /props directory:

      home]$ cd server/default/props/
    2. Open sip-servlets-roles.properties (using your preferred editor) and append the following information to the file:

       
      # A sample roles.properties file for use with some roles
      # Each line in this file assigns roles to the users defined in 
      # sip-servlets-users.properties
      admin=caller,role1,role2,..
                  
  4. Add the Security Domain to the SIP Application

    1. Open the jboss-web.xml file for the SIP application to which security is required.

    2. Add the <security-domain> element as a child of the <jboss-web> element:

      
      
      <jboss-web >
      <!--Uncomment the security-domain to enable security. You will need to edit the htmladaptor-->
      <!--login configuration to setup the login modules used to authentication users.-->
        <security-domain>java:/jaas/sip-servlets</security-domain>
      </jboss-web >
                  
  5. Add Security Constraints to the SIP Application

    1. Open the sip.xml file for the SIP application.

    2. Add the <security-domain> element as a child of the <jboss-web> element:

      
      
      <security-constraint>
        <display-name>REGISTER Method Security Constraint</display-name>
        <resource-collection>
          <resource-name>SimpleSipServlet</resource-name>
          <description>Require authenticated REGISTER requests</description>
          <servlet-name>SimpleSipServlet</servlet-name>
          <sip-method>REGISTER</sip-method>
        </resource-collection>
        <auth-constraint>
          <role-name>caller</role-name>
        </auth-constraint>
      </security-constraint>
      <login-config>
        <auth-method>DIGEST</auth-method>
        <realm-name>sip-servlets-realm</realm-name>
      </login-config>

The Session Traversal Utilities for NAT (STUN) prococol is used in Network Address Translation (NAT) traversal for real-time voice, video, messaging, and related interactive IP application communications. This light-weight, client-server protocol allows applications passing through a NAT to obtain the public IP address for the UDP connections the application uses to connect to remote hosts.

STUN support is provided at the SIP connector level, using the STUN for Java project. The STUN for Java project provides a Java implementation of the STUN Protocol (RFC 3489), which allows each SIP connector to select whether it should use STUN to discover a public IP address, and use this address in the SIP messages sent through the connector.

To make a SIP connector STUN-enabled, three attributes must be appended to the <connector> child element in the server.xml file. The properties are:

  • useStun="true"

    Enables STUN support for this connector. Ensure that the ipAddress attribute is not set to 127.0.0.1

  • stunServerAddress="<Public_STUN_Server>"

    STUN server address used to discover the public IP address of this SIP Connector. See Table 7.1, “Public STUN Servers”for a suggested list of public STUN servers.

  • stunServerPort="3478"

    STUN server port of the STUN server used in the stunServerAddress attribute. Both TCP and UDP protocols communicate with STUN servers using this port only.

Note

A complete list of available SIP connector attributes and their descriptions is located in the Section 2.3.1, “Configuring SIP Connectors” section of this guide.

A number of public STUN servers are available, and can be specified in the stunServerAddress. Depending on the router firmware used, the STUN reply packets' MAPPED_ADDRESS may be changed to the router's WAN port. To alleviate this problem, certain public STUN servers provide XOR_MAPPED_ADDRESS support. Table 7.1, “Public STUN Servers” provides a selection of public STUN servers.


The Seam Telco Framework (STF) is a telecommunications application framework based on the JSR-289 specification, and JBoss Seam. The framework plugs the SIP Servlets 1.1 stack and the Media Server Control API into new or existing JBoss Seam applications. This allows Seam components to implement both the Web and telecommunication logic of the applications.

The primary goals of the STF are to:

From an integration perspective, JBoss Seam provides access to different frameworks. These frameworks are made available to the telecommunication-specific applications for a particular role using the same context. The STF manages SipServletRequests and Media Server events while utilising existing JBoss Seam framework benefits, including:

Other advantages associated with the STF include:

More information about the STF can be found on the STF homepage. For information about JBoss Seam, refer to the community documentation.

The Diameter Protocol (RFC 3588) is a computer networking protocol for Authentication, Authorization, and Accounting (AAA). the Diameter version included in Mobicents SIP Servlets currently support Base, Sh, Ro and Rf.

For more information regarding Diameter support, refer to the Diameter Home Page. For a list of Diameter examples, refer to Chapter 4, SIP Servlet Example Applications.

SIP Extensions in the SIP Servlets Server are based on Internet Engineering Task Force (IETF) Request for Comments (RFC) protocol recommendatons. Table 7.2, “Supported SIP Extensions” lists the supported RFCs for the SIP Servlets Server.


IMS Private Header (P-Header) Extensions are provided according to the recommendations of the 3rd Generation Partnering Project (3GPP), and the IETF. P-Header extensions are primarily used to store information about the networks a call traverses, including (but not limited to) security or call charging details.

Table 7.3, “IMS P-Header Extensions” describes the list of supported P-Headers, including links to the relevant ITEF memorandum where available.

Table 7.3. IMS P-Header Extensions

ExtensionDescription
AuthorizationHeaderIMSDefines a new auth-param for the Authorization header used in REGISTER requests.
PAccessNetworkInfoHeaderContains information regarding the access network the User Agent (UA) uses to connect to the SIP Proxy. The information contained in this header may be sensitive, such as the cell ID, so it is important to secure all SIP application that interface with this header.
PAssertedIdentityHeaderContains an identity resulting from an authentication process, derived from a SIP network intermediary. The identity may be based on SIP Digest authentication.
PAssertedServiceHeaderContains information used by "trust domains", according to Spec(T) specifications detailed in RFC 3324.
PAssociatedURIHeaderContains a list of URIs that are allocated to the user. The header is defined in the 200 OK response to a REGISTER request. It allows the User Agent Client (UAC) to determine the URIs the service provider has associated to the user's address-of-record URI.
PathHeaderSIP Extension header, with syntax similar to the RecordRoute header. Used in conjunction with SIP REGISTER requests and 200 class messages in response to REGISTER responses.
PCalledPartyIDHeaderTypically inserted en-route into an INVITE request by the proxy, the header is populated with the Request_URI received by the proxy in the request. The header allows the User Agent Server (UAS) to identify which address-of-record the invitation was sent to, and can be used to render distinctive audio-visual alert notes based on the URI.
PChargingFunctionAddressesHeaderContains a list of one or more of the Charging Collection Function (CCF) and the Event Charging Function (ECF) addresses. The CCF and ECF addresses may be passed during the establishment of a dialog, or in a standalone transaction.
PChargingVectorHeaderContains a unique charging identifier and correlation information, which is used by network operators to correctly charge for routing events through their networks.
PMediaAuthorizationHeaderContains one or more session-specific media authorization tokens, which are used for QoS of the media streams.
PPreferredIdentityHeaderContains a SIP URI and an optional display-name. For example, "James May" <sip:james@domain.com>. This header is used by trusted proxy servers to identify the user to other trusted proxies, and can be used to select the correct SIP URI in the case of multiple user identities.
PPreferredServiceHeaderUsed by the PAssertedService Header to determine the preferred user service. Multiple PPreferreedService headers may be present in a single request.
PProfileKeyHeaderContains a key used by a proxy to query the user database for a given profile. The key may contain wildcards that are used as part of the query into the database.
PrivacyHeaderContains values that determine whether particular header information is deemed as private by the UA for requests and responses.
PServedUserHeaderContains an identity of the user that represents the served user. The header is added to the initial requests for a dialog or standalone request, which are then routed between nodes in a trusted domain.
PUserDatabaseHeaderContains the address of the HSS handling the user that generated the request. The header field is added to request routed from an Interrogating Call Session Control Function (I-CSCF) to a Serving Call Session Control Function (S-CSCF)
PVisitedNetworkIDHeaderContains the identifier of a visited network. The identifier is a text string or token than it known by both the registrar or the home proxy at the home network, and the proxies in the visited network.
SecurityClientHeader, SecurityServerHeader, SecurityVerifyHeaderContains information used to negotiate the security mechanisms between a UAC, and other SIP entities including UAS, proxy and registrar.
ServiceRouteHeaderContains a route vector that will direct requests through a specified sequence of proxies. The header may be included by a registrar in response to a REGISTER request.
WWWAuthenticateHeaderImsExtends the WWWAuthenticateResponse header functionality by defining an additional authorization parameter (auth-param).

Mobicents Sip Servlets is compatible with the Torquebox Telco Framework JRuby on Rails integration. The framework allows you to create powerful, pure or converged VoIP JRuby on Rails applications.

JRuby features a powerful and well deployed scripting language that allows you to modify your application at runtime (this is true even for the SIP and Media part that Mobicents SIP Servlets offer) without restarting the server. In addition, TorqueBox is a new kind of Ruby application platform that integrates popular technologies such as Ruby-on-Rails, while extending the footprint of Ruby applications to include support for Job Scheduling, Task Queues, SOAP Handling, and other capabilities.

To obtain more information about building pure JRuby-Rails applications that leverage Mobicents SIP Servlets SIP and mediat capabilities, refer to the Torquebox User Documentation.

Check this blog post to help you create your first pure Torquebox JRuby Telco application and our pure JRuby on Rails TorqueBox Telco example showcasing this integration.

JAIN SLEE is a more complex specification than SIP Servlets, and it has been know as heavyweight and with a steep learning curve. However JAIN SLEE has standardized a high performing event driven application server, an execution environment with a good concurrency model and powerful protocol agnostic capabilities thus covering a variety of Telco protocols.

SIP Servlets on the other hand is much simpler and easier to get started with. Its focus is on extending the HTTP Servlets and Java EE hosting environments with SIP capabilities. SIP Servlets is more of a SIP programming framework, while JSLEE is a complete, self sufficient application platform. The fact that SIP Servlets is focused on SIP and Java EE makes it a natural fit to build JEE converged applications.

Table 7.4. SIP Servlets / JAIN SLEE Comparison Table

SIP ServletsJAIN SLEE
Application Architecture
Based on HTTP Servlets. Unit of logic is the SIP ServletsComponent based, Object Orientated architecture. Unit of logic is the Service Building Block
Composition through Application RouterComposition through parent-child relationship
Application State
Servlets are statelessSBBs may be stateful.
Shared state stored in a session and visible to all Servlets with access to the sessionSBB state is transacted and a property of the SBB itself. Shared state may be stored in a separate ActivityContext via a type safe interface
Concurrency Control
Application managed : use of Java monitorsSystem Managed : isolation of concurrent transactions
Facilities (Utilities for Applications)
Timer, ListenersTimer, Trace, Alarm, Statistics, Profiles.
Protocol Support
SIP and HTTPProtocol agnostic. Consistent event model, regardless of protocol/resource
Availability Mechanisms
Container managed state (session object) that can be replicatedContainer managed state (SBB CMP, Facility, ActivityContext) that can be replicated
No transaction context for SIP message processingTransaction context for event delivery
Non transacted state operationsContainer managed state operations are transacted
Facilities are non transactedFacilities, timers, are transacted
No defined failure modelWell defined and understood failure model via transactions
Management
No standard management mechanisms definedJMX Interface for managing applications, life cycle, upgrades, ...


JSLEE and SIP Servlets target different audiences with different needs but they can be complementary in a number of real world cases.

SIP Servlets focuses on SIP and its integration with Java EE. It is also more of a SIP framework within Java EE while JSLEE is an event driven application server with protocol agnostic architecture, spanning any legacy or potential future protocols. SIP Servlets applications are generally simpler to implement and accelerate time to market for Web and SIP deployment scenarios. JSLEE has a steeper learning curve and covers a wider set of target deployment environments.

As JBoss is the only vendor to implement both specifications through Mobicents, this makes it a natural fit to build converged and interoperable JSLEE/SIP Servlets applications that are able to comply with standards in a portable manner, we built an application that could leverage standards all the way without resorting to vendor proprietary extensions by making SIP Servlets and JSLEE work together. Our "JSLEE and SIP-Servlets Interoperability with Mobicents Communication Platform" paper describes our approach and the possible different approaches we have identified to achieve the goal of interoperability between SIP Servlets and JSLEE.

You can also use our JSLEE/SIP Servlets interoperability example showcasing our approach.

This chapter discusses Best Practices related to Mobicents SIP Servlets usage in real world deployments.

Because the default profile of Mobicents SIP Servlets is targeted at a development environment, some tuning is required to make the server performance suitable for a production environment.

To ensure the server is finely tuned for a production envirionment, certain configuration must be changed. Visit the JBoss Application Server Tuning wiki page to learn about optimization techniques.

While it is preferrable to have a fast Application Server, most of the information doesn't apply to Mobicents. In summary, the most important optimization technique is to remove logs, leaving only what is required.

Check the log configuration file in the following location and review the information.

$JBOSS_HOME/server/default/conf/jboss-log4j.xml

The stack can be fine-tuned by altering the SIP stack properties, defined in the external properties file specified by the sipStackPropertiesFile attribute as described in Section 2.3.1, “Configuring SIP Connectors”.

  • gov.nist.javax.sip.THREAD_POOL_SIZE

    Default value: 64

    This thread pool is responsible for parsing SIP messages received from socket messages into objects.

    A smaller value will make the stack less responsive, since new messages have to wait in a queue for free threads. In UDP, this can lead to more retransmissions.

    Large thread pool sizes result in allocating resources that are otherwise not required.

  • gov.nist.javax.sip.REENTRANT_LISTENER

    Default value: true

    This flag indicates whether the SIP stack listener is executed by a single thread, or concurrently by the threads that parse the messages.

    Mobicents SIP Servlets expects this flag to be set to true, therefore do not change the value.

  • gov.nist.javax.sip.LOG_MESSAGE_CONTENT

    Default value: true

    Set the parameter to false to disable message logging.

  • gov.nist.javax.sip.TRACE_LEVEL=0

    Default value: 32.

    Set the parameter to 0 to disable JAIN SIP stack logging.

  • gov.nist.javax.sip.RECEIVE_UDP_BUFFER_SIZE=65536 and gov.nist.javax.sip.SEND_UDP_BUFFER_SIZE=65536

    Default value: 8192.

    Those properties control the size of the UDP buffer used for SIP messages. Under load, if the buffer capacity is overflown the messages are dropped causing retransmissions, further increasing the load and causing even more retransmissions

The full list of JAIN SIP stack properties is available from the SIP Stack Properties Home Page and the full list of implementation specific properties are available from the SIP Stack Implementation Home Page.

The following tuning information applies to Sun JDK 1.6, however the information should also apply to Sun JDK 1.5.

To pass arguments to the JVM, change $JBOSS_HOME/bin/run.conf (Linux) or $JBOSS_HOME/bin/run.bat (Windows).

  • Garbage Collection

    JVM ergonomics automatically attempt to select the best garbage collector. The default behaviour is to select the throughput collector, however a disadvantage of the throughput collector is that it can have long pauses times, which ultimately blocks JVM processing.

    For low-load implementations, consider using the incremental, low-pause, garbage collector (activated by specifying -XX:+UseConcMarkSweepGC -XX:+CMSIncrementalMode ). Many SIP applications can benefit from this garbage collector type because it reduces the retransmission amount.

    For more information please read: Garbage Collector Tuning

  • Heap Size

    Heap size is an important consideration for garbage collection. Having an unnecessarily large heap can stop the JVM for seconds, to perform garbage collection.

    Small heap sizes are not recommended either, because they put unnecessary pressure on the garbage collection system.

In a production environment, it is common to see SIP and Media data passing through different kinds of Network Address Translation (NAT) to reach the required endpoints. Because NAT Traversal is a complex topic, refer to the following information to help determine the most effective method to handle NAT issues.

Revision History
Revision 3.0Thu Jun 11 2009Jared Morgan
Second release of the "parameterized" documentation.
Revision 2.0Fri Mar 06 2009Douglas Silas
First release of the "parameterized", and much-improved JBCP documentation.