JBoss.orgCommunity Documentation

Chapter 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

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.

The Mobicents SIP Servlets Eclipse Tools assist developers in creating JSR 289 applications with Mobicents. You can use the Dynamic Web Project wizard for Converged Applications to get started with an empty project and then you can test your application with a real SIP Phone right from the IDE.