Restcomm SIP Servlets User Guide Server
User Manual:
Open the PDF directly: View PDF 
.
Page Count: 122
| Download | |
| Open PDF In Browser | View PDF |
Restcomm SIP Servlets User Guide
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1. Overview of Restcomm SIP Servlets within the Telecommunications Industry . . . . . . . . . . . . . . 2
1.2. Overview of SIP Servlets Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
2. SIP Servlets Server-Installing, Configuring and Running . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.1. Getting Started with Restcomm for JBoss AS7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.2. Getting Started with Restcomm SIP Servlets for Tomcat 7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
2.3. Sip Connectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
3. Application Router . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
3.1. Default Application Router . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
3.2. DFC Application Router . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
4. SIP Servlet Example Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
4.1. Operating the Example Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
5. Understanding Restcomm High Availabilty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
5.1. Load Balancer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
5.2. Restcomm Graceful Shutdown . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
6. Enterprise Monitoring and Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
6.1. JMX Monitoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
7. Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
7.1. SIP Servlets Application Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
7.2. TLS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
8. Advanced Features of the SIP Servlets Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
8.1. Media Support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
8.2. Concurrency and Congestion Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
8.3. STUN Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
8.4. Restcomm vendor-specific Extensions to JSR 289 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
8.5. CDI Telco Framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
8.6. Diameter Support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
8.7. SIP and IMS Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
8.8. SIP Servlets - JAIN SLEE Interoperability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
8.9. Eclipse IDE Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
9. Best Practices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
9.1. Restcomm SIP Servlets Performance Tips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
9.2. NAT Traversal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
10. Apendix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
10.1. Java Development Kit (): Installing, Configuring and Running . . . . . . . . . . . . . . . . . . . . . . . . . 114
11. JSR 289 Errata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
11.1. Restcomm SIP Servlets Deviations from JSR 289 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
This user guide will help you get a better understanding of Restcomm SIP
servlets and how the container can be used in an enterprise context. The guide
will cover how to how to quickly get started with Restcomm SIP servlets either
on top of JBoss or Apache Tomcat containers. There are sample applications
included for those who want to grasp how to build SIP applications. You will also
learn how to use advanced features like High Availability through Clustering
and Failover. Finally, monitoring and security will be explained.
1
Chapter 1. Introduction
1.1. Overview of Restcomm SIP Servlets within the
Telecommunications Industry
The Restcomm Communication Platform is the best architecture to create, deploy and manage
services and applications integrating voice, video and data across a range of IP and legacy
communications networks. It drives convergence with the following key enablers:
Figure 1. Restcomm Architecture Overview
1.2. Overview of SIP Servlets Server
Restcomm SIP Servlets is a modern communications middleware platform. RestcommSIP Servlets
facilitates the shift towards Cloud Communications by enabling deployment and autoscaling of real
time SIP Servlets apps across all major IaaS (Infrastructure as a Service) providers and also brings
realtime communications (voice and video) to your Browser using HTML5 WebRTC and SIP Over
WebSockets !
The link:
HTML5 WebRTC Client allows you to make video calls from and to any Web Browser
supporting WebRTC , (only Google Chrome supports it so far but all major browsers should support
it in the next 6 months) as well as SIP Endpoints.
Restcomm SIP Servlets enables turnkey SaaS offerings such as RestComm .
Restcomm SIP Servlets implements the latest SIP Servlet v1.1 (JSR 289) standard. It can be plugged
into any Application Server container (currently 7.X and JBoss 7.X) and also offers High Availability
and Failover.
Restcomm SIP Servlets is lead by TeleStax, Inc . and developed collaboratively by a community of
individual and enterprise contributors.
2
Figure 2. Restcomm WebRTC SIP Stack
3
Chapter 2. SIP Servlets Server-Installing,
Configuring and Running
2.1. Getting Started with Restcomm for JBoss AS7
Features not yet available on Restcomm for JBoss AS7
• SIP Failover
• SNMP
• Jopr Monitoring
Some of the features mentioned above will likely be added in the future. As of the time of this
writing, they are not available. Even though Jopr monitoring is not available, there is a Command
Line Interface (CLI), which will be discussed further down. As the features become available, this
guide will be updated to reflect the changes.
2.1.1. Downloading and Starting Restcomm SIP Servlets for JBoss AS7
If you have been working with JBoss for some time, you will quickly notice that the JBoss AS7
iteration has gone through a lot of changes. This guide will help you understand how you can
quickly get started with JBoss AS7 within the Restcomm framework.
You can go to the link below to download the latest Restcomm SIP Servlets for JBoss AS7: link:
Download Latest Version of Restcomm SIP Servlets for JBoss AS7
You will need to extract the content of the file into a directory on your local system. The root
directory of the Restcomm SIP Servlets for JBoss AS7 that you downloaded will be referred to in this
guide as $JBOSS_HOME.
If this is your first time working with Restcomm SIP Servlets for JBoss, you will need to make sure
you have Java Run Time or JDK installed on your computer. You will also need to have the
environment variables set. See the links below to learn how to get JRE or JDK setup on your system.
Installing and Configuring JDK
Setting Environment Variables
1. Starting Restcomm SIP Servlets for JBoss AS7 To start the server do the following:
$JBOSS_HOME/bin/standalone.sh
During the startup process, you will notice that the final part of the log output will be similar to the
truncated output below. Notice that the Admin Console interface can be accessed at
http://172.0.0.1:9990. This will be explained later.
4
14:28:43,972 INFO [org.jboss.as] (Controller Boot Thread) JBAS015951: Admin console
listening on http://127.0.0.1:9990
14:28:43,974 INFO [org.jboss.as] (Controller Boot Thread) JBAS015874: JBoss AS
7.1.2.Final "Steropes"
started in 22148ms - Started 222 of 306 services (83 services are passive or ondemand)
You will notice that the startup is very fast. The reason for this is that JBoss was rewritten from the
ground up for speed with services being started concurrently and non critical services remain
passive until first use. This provides better system resource management. With the simple startup
above, you will be able to enter the default web interface of the application server by going to this
url http://127.0.0.1:8080. The result will show a screenshot similar to the one below.
Figure 3. JBoss Application Server 7 Welcome Page
With the standard startup script, you will not have access to any SIP functionalities. This is because
of the modular approach implemented in JBoss AS7. There is a configuration file that needs to be
used to activate additional functionalities like SIP and High Availability.
In order to start the Restcomm SIP Servlets for JBoss AS7 with SIP functionalities, you need to
append the startup script with the SIP configuration file. The configuration files are located in the
$JBOSS_HOME/standalone/configuration directory. You can see the content of the directory below
application-roles.properties
application-users.properties
dars
logging.properties
mgmt-users.properties
mss-sip-stack.properties
standalone-full-ha.xml
standalone-full.xml
standalone-ha.xml
standalone-sip.xml
standalone.xml
standalone_xml_history
5
Starting Restcomm SIP Servlets for JBoss AS7 with SIP
If you want to start Restcomm SIP Servlets with SIP services activated, you need to go to the
$JBOSS_HOME/bin directory. Type the following command:
./standalone.sh -c standalone-sip.xml
1. You will see a message similar to the one below once the server is successfully started
20:43:21,487 INFO [org.jboss.as.server] (ServerService Thread Pool -- 37) JBAS018559:
Deployed "click2call.war"
20:43:21,489 INFO [org.jboss.as.server] (ServerService Thread Pool -- 37) JBAS018559:
Deployed "sip-servlets-management.war"
20:43:21,647 INFO [org.jboss.as] (Controller Boot Thread) JBAS015951: Admin console
listening on http://127.0.0.1:9990
20:43:21,648 INFO [org.jboss.as] (Controller Boot Thread) JBAS015874: JBoss AS
7.1.2.Final "Steropes" started in 26560ms - Started 232 of 321 services (88 services
are passive or on-demand)
The click2call SIP sample application bundled with Restcomm SIP Servlets will become available at
this url http://127.0.0.1:8080/click2call. You can configure multiple SIP softphones to use the sample
application. See the section below for how to configure and test the SIP sample application.
2.1.2. Testing Click2Call with Restcomm SIP Servlets for JBOSS AS7
Once the server is started as stated in the previous section, you can configure multiple instances of
any SIP softphone you prefer. In this example, Linphone will be used.
6
(configuring two instances of Linphone)
start Linphone
go to the Options menu
On the Network Settings tab,
SIP (UDP) port to 5061. (leave the rest as default)
On the Manage SIP Accounts tab,
click the add button
Your SIP identity: = sip:linphone@127.0.0.1:5080
SIP Proxy address: = sip 127.0.0.1:5080
Leave the rest of the settings as default.
Configuring Linphone (on the second shell)
go to the Options menu
On the Network Settings tab,
SIP (UDP) port to 5062. (leave the rest as default)
On the Manage SIP Accounts tab,
click the add button
Your SIP identity: = sip:linphone2@127.0.0.1:5080
SIP Proxy address: = sip 127.0.0.1:5080
Leave the rest of the settings as default.
A correctly configured Linphone will look like the screenshot below.
7
Figure 4. Successfully Configured Linphone
Once the phones are successfully registered with the Restcomm SIP Servlets for JBoss AS7 server,
you can check the result in the sample SIP application at this url, http://127.0.0.1:8080/click2call
Figure 5. Click2call SIP Registered Softphones
You can make calls from the sample click2call application and see the logs in the shell terminal you
used to start the Restcomm SIP Servlets for JBoss AS7 server.
8
2.1.3. Command Line Interface for Restcomm SIP Servlets JBoss AS7
Part of the task of any administrator who has to manage a JBoss server will be to monitor services
offered to clients. There is a command line interface bundled with JBoss AS7 which can be accessed
by going to the $JBOSS_HOME/bin directory.
You need to make sure that the JBoss server is running on your system and listening on port 9999.
The section below will work you through steps to familiarize yourself with the CLI.
There are so many features available with the Restcomm SIP Servlets for JBoss AS7 CLI. The
example below will concentrate on getting data from the SIP you started using the [path]_
./standalone.sh -c standalone-sip.xml _ script.
In the $JBOSS_HOME/bin directory, type
./jboss-cli.sh
(This will show the message below)
You are disconnected at the moment.
Type 'connect' to connect to the server or
'help' for the list of supported commands.
At the [disconnected /] command prompt, type
connect
When you see the [standalone@localhost:9999 /] at the prompt, you are successfully connected to
the server.
Navigating the CLI
Moving around the Restcomm SIP Servlets for JBoss AS7 CLI is similar to normal
file system with a few exceptions. You can use commands like, (ls, cd, cd..) to
navigate around the CLI
Follow the steps below to access SIP information from the CLI
At the prompt type (ls)
[standalone@localhost:9999 /] ls
core-service
deployment
interface
path
subsystem
system-property
management-major-version=1
management-minor-version=2
namespaces=[]
process-type=Server
product-version=undefined
profile-name=undefined
extension
socket-binding-group
launch-type=STANDALONE
name=linux-fedora
product-name=undefined
release-codename=Steropes
9
release-version=7.1.2.Final
server-state=running
running-mode=NORMAL
schema-locations=[]
[standalone@localhost:9999 /] cd deployment
[standalone@localhost:9999 deployment] ls
click2call.war
sip-servlets-management.war
[standalone@localhost:9999 deployment] cd click2call.war
[standalone@localhost:9999 deployment=click2call.war] ls
subdeployment
subsystem
content=[{"path" => "deployments/click2call.war","relative-to" =>
"jboss.server.base.dir","archive" => true}]
enabled=true
name=click2call.war
persistent=false
runtime-name=click2call.war
status=OK
[standalone@localhost:9999 deployment=click2call.war] cd subsystem
[standalone@localhost:9999 subsystem] ls
sip
web
[standalone@localhost:9999 subsystem] cd sip
[standalone@localhost:9999 subsystem=sip] ls
servlet
active-sip-application-sessions=7
active-sip-sessions=8
app-name=org.mobicents.servlet.sip.example.SimpleApplication
expired-sip-application-sessions=25
expired-sip-sessions=26
max-active-sip-sessions=-1
rejected-sip-application-sessions=0
rejected-sip-sessions=0
sip-application-session-avg-alive-time=180
sip-application-session-max-alive-time=230
sip-application-sessions-created=32
sip-application-sessions-per-sec=0.0
sip-session-avg-alive-time=162
sip-session-max-alive-time=180
sip-sessions-created=34
sip-sessions-per-sec=0.0
10
No SIP data on the CLI
The data from the SIP subsystem are only available if you have the click2call
sample application running and your softphones are connected to the server.
1. SIP Servlets Management Console There is also a SIP servlets management console that is
available at this url http://127.0.0.1:8080/sip-servlets-management. The resulting page will be
similar to the screenshot below. More information will be provided about the SIP servlets
management console in later chapters of this guide.
Figure 6. JBoss Application Server 7 Management Console
2.1.4. Accessing Management Console
Restcomm SIP Servlets for JBoss AS7 provides a management console that can be useful for
accessing vital information about your server. In the welcome page that appears when you access
http://127.0.0.1:8080, there is a link that points to the Administration Console.
If you don’t have a user account for the management console, you will see a screenshot like the one
below. It contains instructions about how to create a user account.
11
Figure 7. Administration Console Error Page
1. Creating a User Account Go to the $JBoss_HOME/bin directory and run the ./add-user.sh script.
You can follow the interactive user mode to create an account for the Administration Console.
Once the user account has been created, you can access the Administration Console at this address
http://127.0.0.1:9990/console/
The screenshot below shows you what the Administration Console looks like.
12
Figure 8. Administration Console
Deleting Administration Console User Account
Deleting the user account isn’t very intuitive. In the event that you will need to
remove an account and create another one, you can remove the account from the
mgmt-users.properties
file.
It
is
located
in
the
$Restcomm_JBoss_HOME/standalone/configuration directory. If you are running
in the domain mode, you will need to check the corresponding configuration
directory.
Installing the Restcomm for JBoss Binary Distribution on
For this procedure, it is assumed that the downloaded archive is saved in the My Downloads folder.
. Create a directory in My Downloads to extract the zip file’s contents into.
For ease of
identification, it is recommended that the version number of the binary is included in the folder
name.
For example, -jboss-. . Extract the contents of the archive, specifying the
destination folder as the one created in the previous step.
You can either use Winzip or the
opensource tool called 7-Zip to extract the content of the donwloaded Restcomm SIP Servlets for
JBoss AS7 file . It is recommended that the folder holding the Restcomm SIP Servlets for JBoss files
(in this example, the folder named -jboss-) is moved to a user-defined location for storing
executable programs. For example, the Program Files folder.
13
Procedure: Running Restcomm SIP Servlets for JBoss on
There are several ways to start Restcomm SIP Servlets for JBoss on Windows. All of the following
methods accomplish the same task.
1. Using Windows Explorer, navigate to the bin subdirectory in the installation directory.
2. The preferred way to start Restcomm SIP Servlets for JBoss from the Command Prompt. The
command line interface displays details of the startup process, including any problems
encountered during the startup process.
Open the Command Prompt via the Start menu and navigate to the correct folder:
C:\Users\My Downloads> cd "-jboss-"
3. Start the JBoss Application Server by executing one of the following files:
• run.bat batch file:
C:\Users\My Downloads\-jboss->bin\run.bat
• run.jar executable Java archive:
C:\Users\My Downloads\-jboss->java -jar bin\run.jar
2.2. Getting Started with Restcomm SIP Servlets for
Tomcat 7
You can download the latest Restcomm SIP Servlets for Tomcat 7 link: Download Latest Version of
for Tomcat 7
The content of the downloaded file can be extracted to any location you prefer on your computer.
The root directory to which the content of the download is extracted will be referred to as
$CATALINA_HOME.
The content of the $CATALINA_HOME/bin is similar to the output below.
bootstrap.jar
catalina.bat
catalina.sh
catalina-tasks.xml
commons-daemon.jar
commons-daemon-native.tar.gz
configtest.bat
configtest.sh
14
cpappend.bat
daemon.sh
digest.bat
digest.sh
setclasspath.bat
setclasspath.sh
shutdown.bat
shutdown.sh
startup.bat
startup.sh
tomcat-juli.jar
tomcat-native.tar.gz
tool-wrapper.bat
tool-wrapper.sh
version.bat
version.sh
You can start Restcomm SIP Servlets for Tomcat 7 by going to $CATALINA_HOME/bin directory and
typing the following:
sudo ./catalina.sh run
The startup process is slightly different from Restcomm SIP Servlets for JBoss AS7. If you see an
output like the one below, you know that Tomcat is correctly started. This is a truncated log from
the startup process.
2012-08-21 22:23:41,025 INFO [SipApplicationDispatcherImpl] (main)
SipApplicationDispatcher Started
2012-08-21 22:23:41,025 INFO [SipStandardService] (main) SIP Standard Service
Started.
Aug 21, 2012 10:23:41 PM org.apache.catalina.startup.Catalina start
INFO: Server startup in 3608 ms
If you get an error message about environment variables or Java, make sure you have the
CATALINA environment variables set.
Setting Environment Variables - JAVA and CATALINA
2.2.1. Testing Click2CallAsync with Restcomm for Tomcat 7
If Restcomm SIP Servlets for Tomcat 7 is started and running, you should be able to use your web
browser to access the welcome page at this url http://127.0.0.1:8080/ This will show you a screenshot
similar to the one below.
15
Figure 9. JBoss Application Server 7 Welcome Page
Deploying your application once the server is running is simple. You need to copy your .War files to
the $CATALINA_HOME/webapps directory.
There is a pre-installed sample SIP application that you can use to test your Restcomm SIP Servlets
Tomcat 7 configuration. The application is also located in the $CATALINA_HOME/webapps directory
Start your web browser and go to the link, http://127.0.0.1:8080/Click2CallAsync/
Sample Application Name
Note that the application name is case-sensitive and will not work if you try to
access it as http://127.0.0.1:8080/click2callasync/
The sample SIP application page will be similar to the screenshot below.
16
Figure 10. SIP Sample Click2CallAsync Application
In order to use the application, you can download a softphone and start multiple instances of the
phone on a single server. In this guide, the softphone that will be used is Linphone. The
configuration is as follows:
Multiple Instances of Linphone
On some Linux systems, you might need to use a different user profile in order to
start a second instance of Linphone. Ex. sudo linphone
17
(configuring two instances of Linphone)
start Linphone
go to the Options menu
On the Network Settings tab,
SIP (UDP) port to 5061. (leave the rest as default)
On the Manage SIP Accounts tab,
click the add button
Your SIP identity: = sip:linphone@127.0.0.1:5080
SIP Proxy address: = sip 127.0.0.1:5080
Leave the rest of the settings as default.
Configuring Linphone (on the second shell)
go to the Options menu
On the Network Settings tab,
SIP (UDP) port to 5062. (leave the rest as default)
On the Manage SIP Accounts tab,
click the add button
Your SIP identity: = sip:linphone2@127.0.0.1:5080
SIP Proxy address: = sip 127.0.0.1:5080
Leave the rest of the settings as default.
Once the softphones are configured and are successfully registered with the Restcomm SIP Servlets
for Tomcat 7 server, you will see a screenshot like the one below in the web browser at this url
http://127.0.0.1:8080/Click2CallAsync/
18
Figure 11. SIP Click2CallAsync with Registers Clients
You can make calls using the application and the softphones you configured will start ringing. It is
important to start Restcomm SIP Servlets for Tomcat 7 in a terminal using the (./catalina.sh run)
script. It will help with troubleshooting SIP calls. The logs you see on the terminal will let you know
when a softphone registers with the Tomcat server and you will also be able to see the status of call
setup and shutdown.
Stopping Restcomm SIP Servlets for Tomcat 7
The best way to stop a server is using the CTRL-D on the terminal in which the server was started. If
you
started
the
Restcomm
$CATALINA_HOME/bin/startup.sh,
SIP
you
Servlets
can
for
Tomcat
stop
7
the
server
using
server
the
using
$CATALINA_HOME/bin/shutdown.sh
2.2.2. Tomcat for Windows
Installing the Restcomm SIP Servlets for Tomcat 7 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 Restcomm
SIP Servlets for Tomcat binary distribution you downloaded. In these instructions, we will refer
to this folder as -tomcat-.
2. Double-click the downloaded zip file, selecting as the destination folder the one you just created
to hold the zip file’s contents.
a. Alternatively, it is also possible to use Java’s jar -xvf command to extract the binary
distribution files from the zip archive. To use this method instead, first move the
19
downloaded zip file from My Downloads to the folder that you just created to hold the SIP
Servlets Server files.
b. Then, open the Windows Command Prompt and navigate to the folder holding the archive
using the cd command.
Opening the Command Prompt from Windows Explorer
If you are using Windows Vista®, you can open the Command Prompt
directly from Explorer. Hold down the Shift key and right-click on either a
folder, the desktop, or inside a folder. This will cause an context menu
item to appear, which can be used to open the Command Prompt with the
current working directory set to either the folder you opened, or opened it
from.
c. Finally, use the jar -xvf command to extract the archive contents into the current folder.
C:\Users\Me\My Downloads\-tomcat->jar -xvf ""
3. At this point, you may want to move the folder holding the Restcomm SIP Servlets for Tomcat
binary files (in this example, the folder named -tomcat-) 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\-tomcat->delete ""
Configuring
Configuring Restcomm SIP Servlets for Tomcat consists in setting the CATALINA_HOME environment
variable and then, optionally, customizing your Restcomm SIP Servlets for Tomcat container by
adding SIP Connectors, configuring the application router, and configuring logging. See Sip
Connectors to learn what and how to configure Restcomm SIP Servlets for Tomcat.
Alternatively, you can simply run your Restcomm SIP Servlets for Tomcat container now and return
to this section to configure it later.
Running
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:
20
Using
Using
Using
Using
CATALINA_BASE:
/home/user/temp/apps/sip_servlets_server/
CATALINA_HOME:
/home/user/temp/apps/sip_servlets_server/
CATALINA_TMPDIR: /home/user/temp/apps/sip_servlets_server/temp
JRE_HOME:
/etc/java-config-2/current-system-vm
Detailed instructions are given below, arranged by platform.
Procedure: Running Restcomm SIP Servlets for Tomcat on Windows
1. There are several different ways to start the Tomcat Servlet Container on Windows. All of the
following methods accomplish the same task.
Using Windows Explorer, change your folder to the one in which you unzipped the downloaded
zip file, and then to the bin subdirectory.
2. Although not the preferred way (see below), it is possible to start the Tomcat Servlet Container
by double-clicking on the startup.bat executable batch file.
a. As mentioned above, the best way to start the Tomcat Servlet Container is by using the
Command Prompt. Doing it this way will allow you to view all of the server startup details,
which will enable you to easily determine whether any problems were encountered during
the
startup
process.
You
can
open
the
Command
Prompt
directly
from
the
\bin folder in Windows Explorer, or you can open the Command Prompt
via the Start menu and navigate to the correct folder:
C:\Users\Me\My Downloads> cd "-tomcat-"
b. Start the Tomcat Servlet Container by running the executable startup.bat batch file:
C:\Users\Me\My Downloads\-tomcat->bin\startup.bat
Stopping
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
Using
Using
Using
CATALINA_BASE:
/home/user/temp/apps/sip_servlets_server
CATALINA_HOME:
/home/user/temp/apps/sip_servlets_server
CATALINA_TMPDIR: /home/user/temp/apps/sip_servlets_server/temp
JRE_HOME:
/etc/java-config-2/current-system-vm
Procedure: Stopping Restcomm SIP Servlets for Tomcat on Windows
1. Stopping the Tomcat Servlet Container on Windows consists in executing the shutdown.bat
21
executable batch script in the bin subdirectory of the SIP Servlets-customized Tomcat binary
distribution:
C:\Users\Me\My Downloads\-tomcat->bin\shutdown.bat
2.3. Sip Connectors
Restcomm SIP Servlets comes with default settings that are designed to get your system up and
running without the need to know about all the detailed configurations. That said, there are
situations in which you might like to fine-tune your setttings to adapt it to your needs. That is what
the following section will help you achieve. You will get a better understand of SIP connectors and
how to make them work for you.
2.3.1. Configuring SIP Connectors and Bindings
There are two important configuration files that you might need to modifying depending on your
system needs. The standalone-sip.xml file in Restcomm SIP Servlets for JBoss AS7 and the
server.xml file in Restcomm SIP Servlets for Tomcat. The extracts below will give you a snapshot of
default configurations.
For JBoss
Changing the ports and other configuration for the SIP connector can be done in the standalonesip.xml file. Below is an extract :
22
Example 1. Adding a SIP Connector to $JBOSS_HOME/standalone/configuration/standalone-sip.xml
If you need to add a connector for the same protocol, a new socket-binding should be created. A
naming convention should be followed for the name attribute of the new socket-binding. The
convention is -sip-. By example,
Attributes
port (defined at the socket-binding element)
The port number on which the container will be able to receive SIP messages.
protocol
Specifies the connector is a SIP Connector and not an HTTP Connector. There is no need to
change this property.
signalingTransport (use socket-binding element)
Specifies the transport on which the container will be able to receive SIP messages. Supported
Values are "udp", "tcp", "tls" and "ws".
23
use-load-balancer
Enable to specify if that particular connector will be using the Load Balancer for outbound
traffic. The Load Balancer to be used is defined by the next load-balancer attributes below
load-balancer-address
Specifies the Load Balancer address used to route outbound traffic for this SIP Connector.
load-balancer-rmi-port
Specifies the RMI Port used to connect to the Load Balancer for this SIP Connector. This enables
the connector to advertise to the Load Balancer the IP and Port it is listening on so that the Load
Balancer can route traffic to that connector as well.
load-balancer-sip-port
Specifies the SIP Port of the Load Balancer to use for outbound traffic for this SIP Connector. This
enables the connector to choose to which Load Balancer it sends outbound traffic. This is
particularly useful for supporting different Load Balancers over different network interfaces
use-stun
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 Restcomm SIP Servlets [_mssstun__stun] for more information about STUN.
stun-server-address
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 Restcomm SIP
Servlets [_mssstun__stun] for more information about STUN and public STUN servers.
stun-server-port
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 Restcomm SIP Servlets [_mssstun__stun] for more information about STUN.
use-static-address
Specifies whether the settings in staticServerAddress and staticServerPort are activated. The
default value is "false" (deactivated).
static-server-address
Specifies what load-balancer server address is inserted 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.
static-server-port
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.
http-follow-sip
Makes the application server aware of how the SIP Load Balancers assign request affinity, and
24
stores this information in the application session.
For Tomcat
Changing the ports and other configuration for the SIP connector can be done in the server.xml file.
Below is an extract.
Example 2. Adding a SIP Connector to $CATALINA_HOME/conf/server.xml
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 .
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".
useLoadBalancer
Enable to specify if that particular connector will be using the Load Balancer for outbound
traffic. The Load Balancer to be used is defined by the next loadBalancer attributes below
loadBalancerAddress
Specifies the Load Balancer address used to route outbound traffic for this SIP Connector.
loadBalancerRmiPort
Specifies the RMI Port used to connect to the Load Balancer for this SIP Connector. This enables
the connector to advertise to the Load Balancer the IP and Port it is listening on so that the Load
25
Balancer can route traffic to that connector as well.
loadBalancerSipPort
Specifies the SIP Port of the Load Balancer to use for outbound traffic for this SIP Connector. This
enables the connector to choose to which Load Balancer it sends outbound traffic. This is
particularly useful for supporting different Load Balancers over different network interfaces
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 Restcomm SIP Servlets [_mssstun__stun] 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 Restcomm SIP
Servlets [_mssstun__stun] 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 Restcomm SIP Servlets [_mssstun__stun] for more information about STUN.
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 inserted 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.
httpFollowsSip
Makes the application server aware of how the SIP Load Balancers assign request affinity, and
stores this information in the application session.
A comprehensive list of implementing classes for the SIP Stack is available from
the Class SipStackImpl page on nist.gov.
2.3.2. Application Routing and Service Configuration
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.
26
The application router is 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.
.
See the example chapters for more information about the Application Router
Configuration for SIP Restcomm SIP Servlets for JBoss AS7
Operating the Example Applications
In order to configure the application router for Tomcat, you should edit the Service element in the
container’s server.xml configuration file
Example 3. Configuring the Service Element in the Container’s server.xml
For Restcomm SIP Servlets for JBoss AS7 this is located in standalone-sip.xml file :
27
Example 4. Configuring the Mobicents SubSystem Element in the Container’s standalone.xml
SIP Service element attributes
className
This attribute specifies that the servlet container is a converged (i.e. SIP + HTTP) servlet
container.
sipApplicationDispatcherClassName (Tomcat) - app-dispatcher-class (JBoss/EAP)
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 (Tomcat) - application-router (JBoss/EAP)
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.
sipStackPropertiesFile (Tomcat) - stack-properties (JBoss/EAP)
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:
usePrettyEncoding (Tomcat) - use-pretty-encoding (JBoss/EAP)
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.
additionalParameterableHeaders (Tomcat) - additional-parameterable-headers (JBoss/EAP)
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.
28
baseTimerInterval (Tomcat) - base-timer-interval (JBoss/EAP)
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).
t2Interval (Tomcat) - t2-interval (JBoss/EAP)
Specifies the T2 Interval, which allows the SIP Servlets container to adjust its timers depending
on network conditions. The default interval is 4000 (milliseconds).
t4Interval (Tomcat) - t4-interval (JBoss/EAP)
Specifies the T4 Interval, which allows the SIP Servlets container to adjust its timers depending
on network conditions. The default interval is 5000 (milliseconds).
timerDInterval (Tomcat) - timerD-interval (JBoss/EAP)
Specifies the Timer D Interval, which allows the SIP Servlets container to adjust its timers
depending on network conditions. The default interval is 32000 (milliseconds).
dialogPendingRequestChecking (Tomcat) - dialog-pending-request-checking (JBoss/EAP)
This property enables and disables error checking when SIP transactions overlap. If within a
single dialog an INVITE request arrives while there is antoher transaction proceeding, the
container will send a 491 error response. The default value is false.
callIdMaxLength (Tomcat) - call-id-max-length (JBoss/EAP)
This property allows to shorten the size of Call-ID Header. This is useful when integrating with
Lync (which has a limit of 32 in size) or older SIP Servers
tagHashMaxLength (Tomcat) - tag-hash-max-length (JBoss/EAP)
This property allows to shorten the size of tags in From and To Header. This is useful when
integrating with Lync (which has a limit of 10 in size) or older SIP Servers
dnsServerLocatorClass (Tomcat) - dns-server-locator-class (JBoss/EAP)
Specifies the org.mobicents.ext.javax.sip.dns.DNSServerLocator implementation class that will
be used by the container to perform DNS lookups compliant with RFC 3263 : Locating SIP Servers
and
E.164
NUmber
Mapping.
The
default
class
used
by
the
container
is
org.mobicents.ext.javax.sip.dns.DefaultDNSServerLocator, but any class implementing the
org.mobicents.ext.javax.sip.dns.DNSServerLocator interface. To disable DNS lookups, this
attribute should be left empty.
dnsResolverClass (Tomcat) - dns-resolver-class (JBoss/EAP)
Specifies the org.mobicents.javax.servlet.sip.dns.DNSResolver implementation class that will be
used by the container to perform DNS lookups compliant with RFC 3263 : Locating SIP Servers
and
E.164
NUmber
Mapping.
The
default
org.mobicents.servlet.sip.dns.MobicentsDNSResolver,
class
but
used
any
by
class
the
container
implementing
is
the
org.mobicents.servlet.sip.dns.DNSResolver interface. To disable DNS lookups, this attribute
should be left empty.
addressResolverClass (Tomcat) - address-resolver-class (JBoss/EAP)
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
29
org.mobicents.servlet.sip.core.DNSAddressResolver,
but
any
class
implementing
the
gov.nist.core.net.AddressResolver NIST SIP Stack interface and having a constructor with a
org.mobicents.servlet.sip.core.SipApplicationDispatcher parameter can be used. To disable
DNS lookups, this attribute should be left empty.
canceledTimerTasksPurgePeriod (Tomcat) - canceled-timer-tasks-purge-period (JBoss/EAP)
Defines a period to due a purge in the container timer schedulers. The purge may prevent
excessive memory usage for apps that cancel most of the timers it sets.
== SIP Servlets Server Logging
Logging is an important part of working with Restcomm SIP Servlets.
There are a few files that you need to be familiar with in order to successfully
troubleshoot and adapt Restcomm SIP Servlets server monitoring and logging to your
environment.
.Logging Files for Restcomm SIP Servlets for JBoss AS7
$JBOSS/standalone/configuration/logging.properties
$JBOSS/standalone/configuration/mss-sip-stack.properties
$JBOSS/standalone/configuration/standalone-sip.xml
.Setting the log file name in $JBOSS/standalone/configuration/standalone-sip.xml
====
[source,xml]
----
---====
The result of the extracted configuration above that is taken from the log4j.xml file
and can be found in the $CATALINA_HOME/logs directory.
JAIN-SIP Stack Logging
There are two separate levels of logging:
• Logging at the container level, which can be configured using the log4j.xml or standalonesip.xml configuration file seen above
• Logging of the JAIN SIP stack, which is configured through the container logging and the SIP
stack properties themselves
You can setup the logging so that the JAIN SIP Stack will log into the container
logs.
To use LOG4J in JAIN SIP Stack in Tomcat, you need to define a category in
[path]_CATALINE_HOME/lib/jboss-log4j.xml_ and set it to `DEBUG`.
.Configuring the JAIN SIP Stack to log into the Tomcat Container's logs
====
[source,xml]
----
---====
32
To use LOG4J in JAIN SIP Stack in JBoss, you need to define a logger in
[path]_JBOSS_HOME/standalone/configuration/standalone-sip.xml_ and set it to
`DEBUG`.
.Configuring the JAIN SIP Stack to log into the JBoss Container's logs
====
[source,xml]
----
---====
For this category to be used in Restcomm SIP Servlets, you need to specify it in
[path]_JBOSS_HOME/standalone/configuration/mss-sip-stack.properties_ or
[path]_CATALINE_HOME/conf/mss-sip-stack.properties_, add the
`gov.nist.javax.sip.LOG4J_LOGGER_NAME=gov.nist` property, and set the
`gov.nist.javax.sip.TRACE_LEVEL=LOG4J` property.
====
**NOTE**
When using ``loadbalanceraddress`` algorithm for LB it is necessary to add the
following at ``mss-sip-stack.properties`` file for the keepalive mechanism:
---org.mobicents.ha.javax.sip.LoadBalancerHeartBeatingServiceClassName=org.mobicents.h
a.javax.sip.MultiNetworkLoadBalancerHeartBeatingServiceImpl
----
33
Chapter 3. Application Router
Application Routing is performed within the Restcomm Sip Servlets container by the Default
Application Router. The following sections describe the Default Application Router, and how other
JSR 289 compliant Application Router implementations can be installed.
3.1. Default Application Router
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.
3.1.1. Role of the Application Router
An Application Router is required for a container to function, but it is a separate logical entity from
the container. The Application Router is 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.
The Application Router is free to make use of any information or data stores, except for the
information passed by the container. 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.
3.1.2. Restcomm Default Application Router
Restcomm SIP Servlets provides an implementation of the Default Application Router (DAR) as
defined in the SIP Servlets 1.1 specification, Appendix C.
The DAR Configuration File
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.
34
In the case of Restcomm SIP Servlets, it is also possible to configure the DAR through the server.xml
configuration file (see [_bsssc_configuring_the_service_element_in_the_containers_server.xml] and
[_wwtssmc_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)..
Restcomm 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 mapping can save time when configuring an application
that listens to all incoming methods.
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
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
35
is removed later on in the routing process, and substituted with the order positions of siprouter-info data.
• An optional string that contains Restcomm -specific parameters. Currently, only the DIRECTION
and REGEX parameters are supported.
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_dar_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
optional 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 selfinitiated the request. The Sip Servlets Management Console can be used to specify the DIRECTION
parameter.
If an application is marked DIRECTION=UAC_ROUTE_BACK, the Application that acted as UAC will be
called back if it present in the list of applications to be called for that particular message SIP
method.
• 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. If it does
not, it is skipped.
For 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 with a From Header with a SIP URI that belongs to the sipservlets.com domain will be passed to the SimpleApplication.
36
Example 5. DIRECTION Example
In
this
example,
two
applications
are
declared
for
the
INVITE
request.
The
LocationServiceApplication is called for requests coming from outside the container, but it will
not be called for the requests initiated by the UAC application Click2DialApplication.
INVITE: ("org.mobicents.servlet.sip.testsuite.Click2DialApplication", "DAR:From",
"ORIGINATING", "", "NO_ROUTE", "0", "DIRECTION=OUTBOUND"), \
("org.mobicents.servlet.sip.testsuite.LocationServiceApplication", "DAR\:From",
"ORIGINATING", "", "NO_ROUTE", "0", "DIRECTION=INBOUND")
This type of configuration is useful in cases where different application must be responsible
for both requests initiated by the container, and external requests received by the container.
Example 6. ORIGINATING/TERMINATING DAR Example
In this example, the DAR is configured to invoke two applications on receipt of an INVITE
request; one each in the originating and the terminating halves. The applications are identified
by their application deployment descriptor names.
INVITE: ("OriginatingCallWaiting", "DAR:From", "ORIGINATING", "", "NO_ROUTE",
"0"), ("CallForwarding", "DAR:To", "TERMINATING", "","NO_ROUTE", "1")
For this example, the returned subscriber identity is the URI from each application’s From and
To headers respectively. The DAR does not return any route to the container, and maintains the
invocation state in the stateInfo as the index of the last application in the list.
Routing of SIP Messages to Applications
Initial Requests and Application Selection Process
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.
There are some other corner cases that apply to initial requests. Refer to
Appendix B, Definition of an Initial Request in the SIP Servlets 1.1 specification.
Example 7. 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.
37
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
38
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.
Response Routing
Responses always follow the reverse of the path taken by the corresponding request. In our case,
the Forbidden response will first go back to the LocationService, and then back to the caller. This is
true for responses to both initial and subsequent requests. The application path is a logical concept
and as such may or may not be explicitly represented within containers.
Another possible outcome could have been that the Call Blocking application, instead of sending a
Forbidden response, allowed the call and proxied the INVITE to the same Request URI chosen by the
Location Service. Then when the callee sends back the 200 OK Response, this response goes back
the same way through the application path (so in the present case Call Blocking, then Location
Service, then back to the caller).
The Call Blocking application cannot just do nothing with the request and expect
the container to route the request in its place (either to a next application in
chain if another one is present or to the outside world if none is present). The
Application has to do something with request (either proxy it or act as a UAS).
Subsequent Requests
Subsequent requests are all requests that are not Initial.
The second scenario, where the Call Blocking application allowed the call, will be used in this
section to showcase subsequent requests. The caller has received the 200 OK response back. Now,
according to the SIP specification (RFC 3261), it sends an ACK. The ACK arrives at the container, and
is not a dialog creating request and is already part of an ongoing dialog (early dialog) so the request
is detected as a Subsequent request and will follow the application path created by the initial
request. The ACK will go through Location Service, Call Blocking, and finally to the callee.
3.1.3. Limitations of the Default Application Router
The DAR
is a minimalist Application Router implementation that is part of the reference
implementation. While it could be used instead of a production Application Router, it offers no
processing logic except for the declaration of the application order.
In real world deployments, the Application Router plays an extremely important role in application
orchestration and composition. It is likely that the Application Router would make use of complex
rules and diverse data repositories in future implementations.
3.2. DFC Application Router
3.2.1. Description of DFC Application Router
Instead of using the Restcomm Default Application Router, any SIP Servlets 1.1 compliant
Application Router can be used, including the eCharts DFC Application Router.
39
3.2.2. Installing the DFC Application Router
Detailed instructions are available from the eCharts website. The following procedure describe how
to install the eCharts DFC Application Router (DFCAR) on a variety of SIP Servlet Server platforms.
Procedure: Installing DFCAR on Tomcat
1. Deploy the DFCAR
Drop the dfcar.jar from the ECharts distribution package in the TOMCAT_HOME/lib directory.
2. Remove the DAR
Remove the Restcomm Default Application Router located in TOMCAT_HOME/lib/sip-servletsapplication-router-*.jar.
Please see the following link to learn how to deploy jar files in Restcomm for JBoss AS7.
Procedure: Installing DFCAR on JBoss AS7
1. Deploy the DFCAR
Create a directory under JBOSS_HOME/modules/system/layers/base/org/echarts/
Drop
the
dfcar.jar
from
the
ECharts
distribution
package
in
the
located
in
JBOSS_HOME/modules/system/layers/base/org/echarts/ directory.
Create a module.xml file under the same directory with the following contents
2. Remove the DAR
Remove
the
Restcomm
Default
Application
Router
JBOSS_HOME/modules/system/layers/base/org/mobicents/dar.
3. Use the DFC DAR
In
JBOSS_HOME/modules/system/layers/base/org/jboss/as/web/main/module.xml,
following line
diameter-event-charging-*.war, from
&VERSION;&VERSION;https://oss.sonatype.org/content/groups/public/org/mobicents/servlet/sip/examples/
diameter-event-charging//diameter-event-charging-.war.
2. Secondly,
download
the
corresponding
Disk
Archive
()
configuration
file
here:
https://sipservlets.googlecode.com/git/sip-servlets-examples/diameter-eventcharging/diametereventcharging-dar.properties.
3. Finally, you will need to download the Ericsson Charging Emulator, version 1.0, from
http://mobicents.googlecode.com/files/ChargingSDK-1_0_D31E.zip.
Installing
The following procedure describes how to install the downloaded files.
1. Place
the
diameter-event-charging-.war
WAR
archive
into
the
$JBOSS_HOME/standalone/deployments/ directory.
2. Place
the
diametereventcharging-dar.properties
DAR
file
in
your
$JBOSS_HOME/standalone/configuration/dars/ directory.
3. Finally, open the terminal, move into the directory to which you downloaded the Ericsson
Charging SDK (for the sake of this example, we will call this directory charging_sdk), and then
unzip the downloaded zip file (you can use Java’s jar -xvf command for this:
~]$ cd charging_sdk
charging_sdk]$ jar -xvf ChargingSDK-1_0_D31E.zip
Alternatively, you can use Linux’s unzip command to do the dirty work:
charging_sdk]$ unzip ChargingSDK-1_0_D31E.zip
Configuration
Restcomm for JBoss
Open the $JBOSS_HOME/standalone/configuration/standalone-sip.xml configuration file and find
the mobicents subsystem element.
48
Example 10. Editing the standalone-sip.xml for the Diameter Event-Changer Service
In the $JBOSS_HOME/standalone/configuration/standalone-sip.xml file search for the line
https://oss.sonatype.org/content/groups/public/org/mobicents/servlet/sip/examples/call
-blocking//call-blocking-.war.
Download the Call-Blocking Service’s DAR file from here: https://sipservlets.googlecode.com/git/sipservlets-examples/call-blocking/call-blocking-servlet-dar.properties.
Installing
Both the call-blocking-.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
Restcomm for JBoss or with Restcomm for Tomcat:
Restcomm for JBoss
Place call-blocking-.war into the $JBOSS_HOME/standalone/deployments/ directory, and callblocking-servlet-dar.properties into the $JBOSS_HOME/standalone/configuration/dars/ directory.
Restcomm for Tomcat
Place call-blocking-servlet-dar.properties into the $CATALINA_HOME/webapps/ directory, and
call-blocking-servlet-dar.properties into the $CATALINA_HOME/conf/dars/ directory.
52
Configuring
Restcomm for JBoss
Open the $JBOSS_HOME/standalone/configuration/standalone-sip.xml configuration file and find
the mobicents subsystem element.
Example 11. Editing MSS for JBoss’s standalone-sip.xml for the Location Service
In the $JBOSS_HOME/standalone/configuration/standalone-sip.xml file search for the line
https://oss.sonatype.org/content/groups/public/org/mobicents/servlet/sip/examples/call
-forwarding//call-forwarding-.war.
Download
the
Call-Forwarding
Service’s
DAR
file
from
here:
https://sipservlets.googlecode.com/git/sip-servlets-examples/call-forwarding/call-forwarding-b2buaservlet-dar.properties.
54
Installing
Both the call-forwarding-.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
Restcomm for JBoss or with Restcomm for Tomcat:
Restcomm for JBoss
Place call-forwarding-.war into the $JBOSS_HOME/standalone/deployments/ directory, and callforwarding-servlet-dar.properties
into
the
$JBOSS_HOME/standalone/configuration/dars/
directory.
Restcomm for Tomcat
Place call-forwarding-.war into the $CATALINA_HOME/webapps/ directory, and call-forwardingservlet-dar.properties into the $CATALINA_HOME/conf/dars/ directory.
Configuring
Restcomm for JBoss
Open the $JBOSS_HOME/standalone/configuration/standalone-sip.xml configuration file and find
the mobicents subsystem element.
Example 13. Editing MSS for JBoss’s standalone-sip.xml for the Location Service
In the $JBOSS_HOME/standalone/configuration/standalone-sip.xml file search for the line
https://oss.sonatype.org/content/groups/public/org/mobicents/servlet/sip/examples/call
-blocking//call-blocking-.war.
Download the Call-Forwarding Service’s WAR file from here: &VERSION;&VERSION;https://oss.sonatype.org/content/groups/public/org/mobicents/servlet/sip/examples/call
-forwarding//call-forwarding-.war.
Download
the
Call-Controller
Service’s
DAR
file
from
here:
https://sipservlets.googlecode.com/git/sip-servlets-examples/call-blocking/call-controller-servletdar.properties.
Installing
The call-blocking-.war, call-forwarding-.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 Restcomm for JBoss or with Restcomm for Tomcat:
Restcomm for JBoss
Place
call-blocking-.war
and
call-forwarding-.war
into
the
$JBOSS_HOME/standalone/deployments/ directory, and call-controller-servlet-dar.properties into
the $JBOSS_HOME/standalone/configuration/dars/ directory.
Restcomm for Tomcat
Place call-blocking-.war and call-forwarding-.war into the $CATALINA_HOME/webapps/ directory,
57
and call-controller-servlet-dar.properties into the $CATALINA_HOME/conf/dars/ directory.
Configuring
RRestcomm for JBoss
Open the $JBOSS_HOME/standalone/configuration/standalone-sip.xml configuration file and find
the mobicents subsystem element.
Example 15. Editing MSS for JBoss’s standalone-sip.xml for the Location Service
In the $JBOSS_HOME/standalone/configuration/standalone-sip.xml file search for the line
element in server.xml for
Tomcat or in the mobicents subsystem element for JBoss AS7.
• The sipPathName attribute must contain the following value org.mobicents.ha.balancing.only
to indicate that the server will be using the Restcomm JAIN SIP HA SIP Stack which is an
extension of the JAIN SIP Stack offering integration with the Mobicents Load Balancer and
transparent replication.
4. Configure the mss-sip-stack.properties configuration file
• The org.mobicents.ha.javax.sip.cache.MobicentsSipCache.cacheName property must contain
the name of the cache that will be responsible for holding the replicated data of the SIP
Stack layer (namely the established SIP dialog data). The value has to be one of the cache
name present in the jboss-cache-manager-jboss-beans.xml file of the jboss-cache-manager
JBoss Service of the container. The default value is standard-session-cache
• The org.mobicents.ha.javax.sip.BALANCERS property must be configured with the list of load
balancer IP address and internal ports. As an example, suppose a single &THIS.PLATFORM;
SIP Load Balancer is running with IP 192.168.0.1 and internal port 5065, the property would
be set with value 192.168.0.1:5065. To specify multiple balancers use ; as separator. If this
property is used the balancers attribute located in server.xml should not be used as it is a
replacement for it.
• The
org.mobicents.ha.javax.sip.LoadBalancerHeartBeatingServiceClassName
property
is
optional, it defines the class name of the HeartBeating service implementation, currently the
only one available is org.mobicents.ha.javax.sip.LoadBalancerHeartBeatingServiceImpl
• The org.mobicents.ha.javax.sip.LoadBalancerElector property is optional, it defines the class
of the load balancer elector from JAIN SIP HA Stack. The elector is used to define which load
67
balancer will receive outgoing requests, which are out of dialog or in dialog with null state.
Currently
only
one
elector
implementation
is
available,
org.mobicents.ha.javax.sip.RoundRobinLoadBalancerElector, which, as the class name says,
uses round robin algorythm to select the balancer.
Configuration File Locations
On Restcomm for Tomcat server installations, server.xml is located in
/conf.
On Restcomm for JBoss server installations, the default standalone-sip.xml
configuration file is located in standalone/configuration or the default domainsip.xml
configuration
file
located
in
domain/configuration
for
cluster
configurations
Easy Node Configuration with JMX
Both SIP Servlet-enabled JBoss and Tomcat have (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 name=-SIPServlets,type=load-balancer-heartbeat-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).
Converged Load Balancing
Apache HTTP Load Balancer
The Restcomm SIP Load Balancer can work in concert with HTTP load balancers such as mod_jk.
Whenever an HTTP session is bound to a particular node, an instruction is sent to the SIP Load
Balancer to direct the SIP calls from the same application session to the same node.
It is sufficient to configure mod_jk to work for HTTP in JBoss in order to enable cooperative load
balancing. Restcomm will read the configuration and will use it without any extra configuration.
You can read more about configuring mod_jk with JBoss in your JBoss Application Server
documentation.
Alternatively you may disable this behaviour and make the HTTP load balancer follow the
decisions made by the SIP load balancer with the httpFollowsSip flag. This is achieved by changing
the jvmRoute part of the session ID cookie used internally by mod_jk.
68
The httpFollowsSip flag
The httpFollowsSip flag in the service configuration makes the application server aware of how
different mod_jk and SIP load balancers have assigned
request affinity for each application
session. The application servers assign exactly one node to each Sip Servlets application session and
this node is the node where the last SIP request associated with the application session has landed
(decised by the SIP load balancer). Then the application server will actively update the session ID
cookie (the jvmRoute part) of any HTTP request that arrives at the wrong node. The application
server will do so with a specially composed HTTP redirect response or with a HTML refresh hint. As
a backup strategy, if the request is bound to seek non-existing node forever and it will let the
request be served by a new node. This avoids having a client stuck reloading the same page over
and over.
One problem with this flag is that if you have two or more SIP sessions associated with the same
application session and the load balancer has decided to send SIP requests to different nodes,
which might happend if you use Call-ID based affinity, then the application server will have to
change the jvmRoute very often for every SIP request resulting in significant overhead. It is
generally not adviced to enable this flag if you have more than 1 SIP session per application session
and the means to guarantee all SIP sessions from the application session will land on the same
node.
This is an example how to enable the option. It is disabled by default.
.. The very first request for each new HTTP session does not have a session ID
assigned; the 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. This response goes back to the client through apache, which keeps track of which
node owns each 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 Balancer is also available. The SIP Load Balancer
has a HTTP port where you can direct all incoming HTTP requests. The integrated HTTP load
balancer behaves exactly like apache by default, but this behavior 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 and
74
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.
5.1.5. Pluggable balancer algorithms
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 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.
Users must be aware that by default requests explicitly addressed to a live server
node passing through the load balancer will be forwarded directly to the server
node. This allows for pre-specified routing use-cases, where the target node is
known by the SIP client through other means. If the target node is dead, then the
node selection algorithm is used to route the request to an available node.
The following is a list of the built-in algorithms:
org.mobicents.tools.sip.balancer.CallIDAffinityBalancerAlgorithm
This algorithm is not distributable. It selects nodes randomly to serve a give Call-ID extracted
from the requests and responses. It keeps a map with Call-ID → nodeId associations and this
map is not shared with other load balancers which will cause them to make different decisions.
For HTTP it behaves like apache.
org.mobicents.tools.sip.balancer.HeaderConsistentHashBalancerAlgorithm
This algorithm is distributable and can be used in distributed load balancer configurations. It
extracts the hash value of specific headers from SIP and HTTP messages to decide which
application server node will handle the request. Information about the options in this
algorithms is available in the balancer configuration file comments.
org.mobicents.tools.sip.balancer.PersistentConsistentHashBalancerAlgorithm
This algorithm is distributable and is similar to the previous algorithm, but it attempts to keep
session affinity even when the cluster nodes are removed or added, which would normally
cause hash values to point to different nodes.
org.mobicents.tools.sip.balancer.ClusterSubdomainAffinityAlgorithm
This algorithm is not distributable, but supports grouping server nodes to act as a subcluster.
Any call of a node that belongs to a cluster group will be preferentially failed over to a node
from the same group. To configure a group you can just add the subclusterMap property in the
load balancer properties and listing the IP addresses of the nodes. The nodes specified in a
group do not have to alive and nodes that are not specified are still allowed to join the cluster.
Otherwise the algorthim behaves exactly as the default Call-ID affinity algorthim. The groups are
75
enclosed in parentheses and the IP addresses are separate by commas as follows:
subclusterMap=( 192.168.1.1, 192.168.1.2 ) ( 10.10.10.10,
30.30.30.30)
20.20.20.20,
5.1.6. Distributed load balancing
When the capacity of a single load balancer is exceeded, multiple load balancers can be used. With
the help of an IP load balancer the traffic can be distributed between all SIP/HTTP load balancers
based on some IP rules or round-robin. With consistent hash and jvmRoute-based balancer
algorithms it doesn’t matter which SIP/HTTP load balancer will process the request, because they
would all make the same decisions based on information in the requests (headers, parameters or
cookies) and the list of available nodes. With consistent hash algorithms there is no state to be
preserved in the SIP/HTTP balancers.
Figure 16. Example deployment: IP load balancers serving both directions for incoming/outgoing
requests in a cluster
5.1.7. Implementation of the Restcomm Load Balancer
Each individual Restcomm SIP Server in the cluster is responsible for contacting the SIP load
balancer and relaying its health status and regular "heartbeats".
From these health status reports and heartbeats, the SIP Load Balancer creates and maintains a list
of all available and healthy nodes in the cluster. The Load Balancer forwards SIP requests between
these cluster nodes, providing that the provisioning algorithm reports that each node is healthy and
76
is still sending heartbeats.
If an abnormality is detected, the SIP Load Balancer removes the unhealthy or unresponsive node
from the list of available nodes. In addition, mid-session and mid-call messages are failed over to a
healthy node.
The SIP Load Balancer first receives SIP requests from endpoints on a port that is specified in its
Configuration Properties configuration file. The SIP Load Balancer, using a round-robin algorithm,
then selects a node to which it forwards the SIP requests. The Load Balancer forwards all samesession requests to the first node selected to initiate the session, providing that the node is healthy
and available.
5.1.8. SIP Message Flow
The 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 an unhealthy status, or irregular heartbeats from a
node.
In advanced configurations, it is possible to run more than one SIP Load Balancer. Simply edit the
balancers connection string in your SIP Server - the list is separated with semi-colon.
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.
77
Figure 17. Basic IP and Port Cluster Configuration
5.2. Restcomm Graceful Shutdown
Graceful
shutdown
of
a
server
or
SIP/Web
Applications
is
when
existing
request/connections/sessions are allowed to gracefully complete while no new requests and/or
connections and/or sessions are accepted. SIP Servlets Container or Applications can be gracefully
shutdown through the Management Console, JMX or CLI as described below
As soon as the shutdown command is given, the container will stop the applications so that they do
not accept any more inbound connections. It will inform also load balancers that the server is no
longer part of the cluster if the command is given on the container and not an individual
application. The Applications are closed so that they do not accept any more requests, but the
requests currently inside the container will drain out and the Server instance will shutdown after
the grace period expires.
5.2.1. Graceful Shutdown through Restcomm SIP Servlets Management
Console
78
Figure 18. Graceful Shutdown of Container through Restcomm SIP Servlets Management Console
5.2.2. Graceful Shutdown of Container or Applications through Restcomm
JBoss AS/EAP Command Line Interface
`To Gracefully shutdown an Application through the CLI `, use the following command
sh bin/jboss-cli.sh --connect
/subsystem=sip:contextGracefulShutdown\(timeToWait=30000,sipApp=appNameFromDeploymentD
escriptor)
`To Gracefully shutdown an Application through the CLI `, use the following command
sh bin/jboss-cli.sh --connect
/subsystem=sip:gracefulShutdown\(timeToWait=30000\)
79
5.2.3. Graceful Shutdown of Container or Applications through Restcomm
SIP Servlets JMX Console
`To Gracefully shutdown an Application through the JMX Console, Find the 'SipManager' MBean
corresponding to your application and go to the 'stopGracefully' operation, Fill out the 'Time To
Wait' Field and click 'Invoke' Button `
`To
Gracefully
shutdown
the
Container
through
the
JMX
Console,
Find
the
'jboss.web:type=SipApplicationDispatcher' MBean and go to the 'stopGracefully' operation, Fill out
the 'Time To Wait' Field and click 'Invoke' Button `
80
Chapter 6. Enterprise Monitoring and
Management
There is two ways of monitoring Restcomm Sip Servlets :
• Through JMX
• Through the industry standard Simple Network Management Protocol - SNMP
• Through the Restcomm Sip Servlets Management Console.
6.1. JMX Monitoring
The default mechanism for monitoring Restcomm Sip Servlets is using the Java Management
Extensions (JMX) technology. The Oracle website includes the list of options and how to configure
JMX
Remote
on
Java
7
http://docs.oracle.com/javase/7/docs/technotes/guides/management/agent.html
Please find below, the list of SIP Specific metrics that can be monitored through JMX
6.1.1. SIP Stack Monitoring Metrics
JMX Name Domain=org.mobicents.jain.sip,name=Mobicents-SIP-Servlets,type=sip-stack provides the
following metrics :
• NumberOfClientTransactions : Active number of SIP Client Transactions.
• NumberOfServerTransactions : Active number of SIP Server Transactions.
• NumberOfDialogTransactions : Active number of SIP Dialogs.
• LocalMode : whether the stack is using replication or not.
6.1.2. Container SIP Core Router (SipApplicationDispatcher) Monitoring
Metrics
JMX Name Domain=,type=SipApplicationDispatcher provides the following metrics :
• RequestsProcessedByMethod : Number of incoming SIP requests that have been processed by SIP
Method name (INVITE, BYE, INFO, …).
• ResponsesProcessedByStatusCode : Number of incoming SIP responses that have been processed
by status code (1xx, 2xx, 3xx, …).
• RequestsSentByMethod : Number of outgoing SIP requests that have been sent by SIP Method
name (INVITE, BYE, INFO, …).
• ResponsesSentByStatusCode : Number of outgoing SIP responses that have been sent by status
code (1xx, 2xx, 3xx, …).
81
6.1.3. Application Level Monitoring Metrics
JMX
Name
Domain=,path=,type=SipManager,host= provides
the following metrics :
• expiredSipSessions : Number of SIP sessions that have expired
• expiredSipApplicationSessions : Number of SIP Application sessions that have expired
• sipSessionAverageAliveTime : the average time (in seconds) that expired SIP sessions had been
alive.
• sipApplicationSessionAverageAliveTime : the average time (in seconds) that expired SIP
Application sessions had been alive.
• sipSessionCounter : Number of SIP Sessions created.
• sipApplicationSessionCounter : Number of SIP Application Sessions created.
• activeSipSessions : Number of currently active SIP Sessions.
• activeSipApplicationSessions : Number of currently active SIP Application Sessions.
• rejectedSipSessions : Number of SIP session creations that failed due to maxActiveSipSessions.
• rejectedSipApplicationSessions : Number of SIP Application session creations that failed due to
maxActiveSipApplicationSessions.
• numberOfSipSessionCreationPerSecond : Number of SIP sessions per second that have been
created.
• numberOfSipApplicationSessionCreationPerSecond : Number of SIP Application sessions per
second that have been created.
6.1.4. JMX Monitoring for Restcomm for JBoss AS7/EAP6
Follow the link To Connect JConsole to JMX on AS7/EAP6.
SNMP Monitoring for Restcomm for JBoss AS7
The SNMP feature is not yet implemented in Restcomm for JBoss AS7. This guide
will be updated when SNMP monitoring feature become available. In the
meantime, see the chapter below for information about the CLI.
Getting Started with Restcomm SIP Servlets for AS7 CLI
6.1.5. JMX Monitoring for Restcomm for Tomcat 7
Follow the link To Connect JConsole to JMX on Tomcat 7.
82
SNMP Monitoring for Restcomm for Tomcat 7
The SNMP feature is not yet implemented in Restcomm for Tomcat 7. This guide
will be updated when SNMP monitoring feature become available.
Chapter 7. Security
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.
There are essentially two levels of security that can be enabled on the server, the communication
between the server and other SIP entities and securing the application and its content.
7.1. SIP Servlets Application Security
Application security varies depending on the server type used. The following procedures describe
how to configure the JBoss AS7 and Tomcat servers to enable Security.
Procedure: Enable SIP Application Security in JBoss AS7
1. Add Security Policy to Server Configuraton
a. Open the configuration file located in $JBOSS_HOME/standalone/configuration/standalonesip.xml
b. Append a security domain to the under the :
2. Create SIP Server User Properties File
a. Open a terminal and navigate to the $JBOSS_HOME/standalone/configuration directory:
home]$ cd standalone/configuration
b. Create and open a sip-servlets-users.properties file and append the user lines to the file:
83
# A sample users.properties file, this line creates user "admin" with
# password "admin" for "sip-servlets-realm"
admin=
c. To create , execute the following command in a terminal:
home]$ java -cp ../../modules/system/layers/base/org/picketbox/main/picketbox4.0.15.Final.jar org.jboss.security.auth.callback.RFC2617Digest admin sipservlets
d. Copy the A1 hash, and paste it into the admin parameter in the previous step.
e. Save and close sip-servlets-users.properties.
3. Create the SIP Server Roles File
a. Create and 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
a. Open the jboss-web.xml file for the SIP application to which security is required.
b. Add the element as a child of the element:
sip-servlets
5. Add Security Constraints to the SIP Application
a. Open the sip.xml file for the SIP application.
b. Add the element as a child of the element:
84
REGISTER Method Security Constraint
SimpleSipServlet
Require authenticated REGSITER requests
SimpleSipServlet
REGISTER
caller
DIGEST
sip-servlets
Procedure: Enable SIP Application Security in Tomcat Server
1. Activate the Memory Realm in Catalina:
a. Open a terminal and navigate to the /conf
directory:
home]$ cd server/default//conf/
b. Open server.xml and uncomment the following line:
2. Update SIP Server User Properties File
a. In the /conf directory, open tomcat-users.xml (using your preferred editor) and append the
following child element:
REGISTER Method Security Constraint
SimpleSipServlet
Require authenticated REGISTER requests
SimpleSipServlet
REGISTER
caller
DIGEST
sip-servlets-realm
7.2. TLS
In order to configure TLS you will have to obtain a public/private key, a X.509 certificate, add those
to the Java keystore and optionally add certificates from a known CA (certicate authority). The
entire process can be confusing but in order to get a basic setup for testing purposes up and
running with minimal effort, this section starts off with a simple quick start. However, for
production environment you need to obtain an officially signed certificate from a known CA and
that process is outlined in section Production Setup.
7.2.1. Quick Start
This section shows how to create a self signed certificate, how to add that to the Java keystore and
how to configure the SIP Servlet Container to make use of this configuration. Note, this section
should only be used in a development environment and the main reason for this quickstart section
is to get you going right away as well as get you comfortable with generating keys and certificates
and adding them to the Java keystore.
Procedure: Server Side Authentication
At a high-level, we will execute the following three steps:
1. Generate a public/private key pair and a self signed certificate and add those to the Java
keystore.
2. Configure the SIP Servlet Container to load our certificate from the keystore.
3. Test!
Let’s follow each step in order:
1. Generate certificate
86
Generating a new key-pair and a certificate can be done in a few different ways with a few
different tools but here we will just use the java keytool that comes with the JDK. Simple issue
the following command, which will generate a new public and private key, generate a selfsigned certificate and add it all to the Java keystore:
keytool -genkeypair -alias myserver -keyalg RSA -keysize 1024 -keypass secret
-validity 365 -storetype jks -keystore myserver.jks -storepass secret -v -dname
"CN=James Smith, OU=Engineering, O=My Company, L=My City, S=My State, C=US"
-keystore specifies which keystore we should use/update. If the keystore doesn’t exist, a new one
will be created for one. In the above example, we named the keystore myserver.jks and it will be
saved in the current directory
-keypass and -storepass should be chosen wisely since with bad passwords you won’t have
much protection anyway. Also, normally you should never passwords on the command prompt,
it is too easy for other people to steal. If you leave these two options out, the keytool command
will ask you for it.
-keyalg specifies which algorithm to use when generating the keys and the keysize how long
those keys should be.
Note: the command -genkeypair is new in JDK 6 and was previously named -genkey. The keytool
in JDK 6 has some improvements over the previous versions so it is recommended to use it
instead.
See
more
about
the
Java
keytool
here:
http://docs.oracle.com/javase/6/docs/technotes/tools/solaris/keytool.html
2. Configure the SIP Servlet Container
The SIP Servlet Container relies on the JAIN SIP stack to support it with TLS capabilities. As
such, it is the JAIN SIP stack that we need to configure to have it read our certificate we added to
the key store. The various configuration options are described in the javadoc of the
SipStackImpl class but for this quickstart, we will be using the following ones:
• javax.net.ssl.keyStore – the filename and location of the keystore to use.
• javax.net.ssl.keyStorePassword – the password to the keystore.
• javax.net.ssl.trustStore – the filename and location of the truststore to use.
• javax.net.ssl.trustStorePassword – the password to the truststore.
• gov.nist.javax.sip.TLS_CLIENT_AUTH_TYPE – which type of authentication we will require of
the client (for now, the client authentication type will be set to Disabled).
• gov.nist.javax.sip.gov.nist.javax.sip.ENABLED_CIPHER_SUITES – Comma-separated list of
suites to use when creating outgoing TLS connections. This parameter is optional with
default
value
"TLS_RSA_WITH_AES_128_CBC_SHA,SSL_RSA_WITH_3DES_EDE_CBC_SHA,TLS_DH_anon_WI
TH_AES_128_CBC_SHA,SSL_DH_anon_WITH_3DES_EDE_CBC_SHA"
87
The configuration options are JVM parameters and you will have to add these to the command
line when you start the server:
+
./bin/run.sh -Djavax.net.ssl.keyStorePassword=mysecret
-Dgov.nist.javax.sip.TLS_CLIENT_AUTH_TYPE=Disabled
-Djavax.net.ssl.keyStore=/path/to/your/keystore/myserver.jks
-Djavax.net.ssl.trustStorePassword=mysecret
-Djavax.net.ssl.trustStore=/path/to/your/keystore/myserver.jks
Once the server is up, we are ready to verify that we can get a TLS connection using the
certificate we previously added in the first step.
+
for this first part of the quickstart we will not require a certificate from the
client since this involves more configuration. This is controlled by the
gov.nist.javax.sip.TLS_CLIENT_AUTH_TYPE parameter.
3. Test!
To verify your setup there are a few different tools that you can use.
• openssl is an open source SSL toolkit and contains a generic SSL/TLS test client
• SIPp – an open source SIP load testing tool that is capable of using TLS. However, it requires
some additional steps that we have not addressed in the first parf of this quickstart so
therefore we willl not be using SIPp.
• Using your favorite SIP client. Most SIP clients out there are capable of establishing a TLS
connection but you will have to consult its documentation of how to configure TLS.
Using openssl:
Assuming that your server is running on localhost and is listening for TLS on port 5081 the
command would be:
openssl s_client -host 127.0.0.1 -port 5081
If you are successful you should see an output from openssl displaying information about
the server certificate (which should be the one we generated in Step 1). If there are any
issues with the setup, openssl is pretty good about giving out information about what it
thinks is wrong.
Tip: if you add the following JVM parameter as well you will get a lot of useful debug
information: -Djavax.net.debug=ssl
Procedure: Server Side Authentication
88
In the first part of this quickstart we generated a public and private key along with a self-signed
certificate and added them all into the Java keystore. The server was then configured to use this
information and when a client connected, our certificate was served up to the client. However,
normally, the client and the server would like to verify each others certificate to make sure they
both trust each other and if not, either of them will terminate the connection. In the first part of the
quickstart, the server did not require the client to present a certificate when connecting (remember
that we set the gov.nist.javax.sip.TLS_CLIENT_AUTH_TYPE to disabled) so let’s do that now.
At a high-level, these are the tasks we need to execute:
1. Generate a public/private key pair for the client along with a certificate.
2. The server need to add the client certificate to its keystore as a trusted certificate.
3. Start the server with client authenticating enabled.
Let’s follow each step in order:
1. Generate Client Certificate
We will use the Java keytool for this step in the same we did for for the server side in the
previous quikstart. The command is exactly the same and the only difference is that we store
the information in a new keystore called myclient.jks.
keytool -genkeypair -alias myclient -keyalg RSA -keysize 1024 -keypass secret
-validity 365 -storetype jks -keystore myclient.jks -storepass secret -v -dname
"CN=John Doe, OU=Engineering, O=Some Work, L=Some City, S=Some State, C=US"
We have now generated a new keystore containing the clients authentication information.
However, the server needs to import the client certificate into its trusted keystore so we need to
extract the certificate out of the client key store. This can also be done using the Java keytool.
keytool -exportcert -alias myclient -file client.cert -keystore myclient.jks
-storepass secret -rfc
The certificate is saved in file 'client.cert' and we will use this file in the next step.
2. Re-configure the server
Simply change the gov.nist.javax.sip.TLS_CLIENT_AUTH_TYPE from 'Disabled' to 'Enabled' and
start the server again.
3. Test
We will once again use openssl to verify our setup but now that the client will be forced to
present a certificate as well, we do need the certificate’s private key as well. The private key is
embedded into the keystore and was generated when we issued the 'kenkeypair' keytoolcommand. Unfortunately, the keytool does not have an option for exporting the private key so
we will have to write a small java program to extract it for us. Luckily, it is not a lot of code:
89
import java.io.FileInputStream;
import java.security.Key;
import java.security.KeyStore;
import sun.misc.BASE64Encoder;
/**
* Code originally posted on Sun's developer forums but
* can now only be found at stackoverflow:
* http://stackoverflow.com/questions/150167/how-do-i-list-export-private-keysfrom-a-keystore
*/
public class DumpPrivateKey {
static public void main(String[] args)
throws Exception {
if(args.length < 3) {
throw new IllegalArgumentException("expected args: Keystore filename,
Keystore password, alias, clientprivate.key
Now that we have the private key of the client we can use openssl to verify the setup again:
openssl s_client -host 127.0.0.1 -port 5081 -cert client.cert -certform PEM -key
clientprivate.key
If all goes well you should successfully establish a connection and openssl will dump
information about the certificate exchange.
7.2.2. Production Setup
In a production environment it is important that you run with an officially signed certificate from a
known CA. It is this certificate that you will load into your keystore and the process is very similar
to the one outlined in the quick start.
1. Generate a PKCS#12 Storage
Assuming that you already have a private key and a signed certificate from a known CA you
first have to wrap these two into a pkcs#12 storage (pkcs#12 is a file format for storing X.509
public certificates along with the private key), and then load that into the Java keystore. To
create a pkcs#12 storage you can use the openssl pkcs12 command:
openssl pkcs12 -inkey myprivate.key -in mycertificate.pem -export -out
mystorage.pkcs12 -passout mysecret
where myprivate.key is the private key, mycertificate.pem is the X.509 certificate. The password
for the storage is 'mysecret' and the name of the storage file is mystorage.pkcs12.
2. Generate the Java Keystore
Once the pkcs#12 has been created, use the Java keytool to load the pkcs12 storage and convert
it into a java keystore.
keytool -importkeystore -srckeystore mystorage.pkcs12 -srcstoretype PKCS12
-destkeystore myserver.jks -deststorepass mysecret -srcstorepass mysecret
A few things to point out:
-srcstoretype is important and tells the Java keytool which format the key store that we are
importing is in. In the previous step, we generated a pkcs#12 store so in this example, the store
type must be PKCS12.
-srcstorepass is the password for the pkcs#12 storage and in the above example it is the same as
91
the destination key store (-deststorepass) but most likely they will be different.
3. Re-configure and Test
Now that we have a java keystore the server configuration is exactly the same as described in
the
quick
start,
i.e.,
simply
set
the
java
properties
javax.net.ssl.keyStore
and
javax.net.ssl.trustStore to point to this key keystore file and then set the password through
the property javax.net.ssl.keyStorePassword and javax.net.ssl.trustStorePassword. Once the
server has been re-started you can use openssl to verify the setup.
7.2.3. Production Setup
In addition to securing your SIP TLS, you may want to secure your HTTPS and SIP Over WebSockets
Connectors too.
1. Secure HTTPS on JBoss 7/EAP 6
Assuming that you already followed the previous steps, you now have a private key and a self
signed
certificate.
You
will
need
to
configure
your $JBOSS_HOME/standalone/configuration/standalone-sip.xml to enable HTTPS connector:
2. Add SIP Over WebSockets Secure Connector
Make
sure
the
following
connector
is
present
in $JBOSS_HOME/standalone/configuration/standalone-sip.xml
Procedure: Tuning RestComm SIP Servlets for Tomcat Server Settings for Concurrency and Congestion
Control
1. Open server.xml File
Open the $CATALINA_HOME/conf/server.xml configuration file in your text editor.
2. Add Parameters to Element
Locate
the
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:
• sipMessageQueueSize="1500"
• backToNormalSipMessageQueueSize="1300"
• congestionControlCheckingInterval="30000" (30 seconds, in milliseconds)
• memoryThreshold="95" (in percentage)
• backToNormalMemoryThreshold="90" (in percentage)
• congestionControlPolicy="ErrorResponse"
Experimentation is required for these tuning parameters depending on the operating
system and server.
98
Tuning Parameters from the dispatcher MBean
Navigate to the dispatcher MBean from Restcomm SIP Servlets for JBoss’s JMX console.
All changes performed at run time are effective immediately, but do not persist across
reboots for Tomcat, only on JBoss AS7. the server.xml must be appended with the settings
in order to make the configuration persistent.
When editing the dispatcher MBean from RestComm SIP Servlets for JBoss’s JMX console,
values allowed for the concurrency control mode are None, SipSession or
SipApplicationSession.
8.3. STUN Support
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 then 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 child element in
the server.xml or child element in standalone-sip.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=""
STUN server address used to discover the public IP address of this SIP Connector. See 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.
A complete list of available SIP connector attributes and their descriptions is
located in the Configuring SIP Connectors and Bindings 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
99
XOR_MAPPED_ADDRESS support. Public STUN Servers provides a selection of public STUN servers.
Table 2. Public STUN Servers
Server Address
XOR Support
DNS SRV Record
stun.ekiga.net
Yes
Yes
stun.fwdnet.net
No
Yes
stun.ideasip.com
No
Yes
stun01.sipphone.com
Yes
No
stun.softjoys.com
No
No
stun.voipbuster.com
No
No
stun.voxgratia.org
No
No
stun.xten.com
Yes
Yes
stunserver.org
Yes
Yes
For more information about NAT traversal best practices, refer to NAT Traversal..
8.4. Restcomm vendor-specific Extensions to JSR 289
Restcomm provide Extensions for applications or external systems to interact with the Restcomm
SIP Servlets container as well as Extensions not defined in the specification in the JSR 289
specification that can prove useful and might be proposed for inclusion in a next release of the SIP
Servlets specification
Javadoc for JSR 289 Extensions
8.5. CDI Telco Framework
CDI is the Java standard for dependency injection and contextual lifecycle management, led by
Gavin King for Red Hat, Inc. and is a Java Community Process(JCP) specification that integrates
cleanly with the Java EE platform. Any Java EE 6-compliant application server provides support for
JSR-299 (even the web profile). It seemed a natural fit create a new framework based on CDI for the
Telco world.
CDI-Telco-Framework (CTF) from Restcomm brings the power and productivity benefits of CDI into
the Restcomm Sip Servlets platform providing dependency injection and contextual lifecycle
management for converged HTTP/SIP applications. This new framework is intended to become a
replacement for our previous Seam Telco Framework.
CTF mission statement is to simplify SipServlets development by introducing a component based
programming model, ease of development by making available SIP utilities out of the box, and
finally providing dependency injection and contextual lifecycle management to the SipServlets.
100
Figure 20. CDI Telco Framework Extension
More information about the CTF can be found on the CDI Telco Framework Documentation.
8.6. Diameter Support
The Diameter Protocol (RFC 3588) is a computer networking protocol for Authentication,
Authorization, and Accounting (AAA). The Diameter version included in Restcomm 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 SIP Servlet Example Applications.
8.7. SIP and IMS Extensions
SIP Extensions in the SIP Servlets Server are based on the Internet Engineering Task Force’s (IETF)
Request for Comments (RFC) protocol recommendations. Supported SIP Extensions lists the
supported RFCs for the SIP Servlets Server.
Table 3. Supported SIP Extensions
Extension
RFC Number
Description
DNS
RFC 3263
SIP: Locating SIP Servers
ENUM
RFC 2916
E.164 number and DNS
INFO
RFC 2976
The SIP INFO Method
IPv6
RFC 2460
Internet Protocol, Version 6
(IPv6) Specification
JOIN
RFC 3911
The SIP "Join" Header
MESSAGE
RFC 3428
SIP Extension for Instant
Messaging
PATH
RFC 3327
SIP Extension Header Field for
Registering Non-Adjacent
Contacts
101
Extension
RFC Number
Description
PRACK
RFC 3262
Reliability of Provisional
Responses in the SIP
PUBLISH
RFC 3903
SIP Extension for Event State
Publication
REASON
RFC 3326
The Reason Header Field for the
Session Initiation Protocol (SIP)
REFER
RFC 3515
The SIP Refer Method
REPLACES
RFC 3891
The SIP "Replaces" Header
STUN
RFC 3489
STUN - Simple Traversal of User
Datagram Protocol (UDP)
through Network Address
Translators (NATs)
SUBSCRIBE/NOTIFY
RFC 3265
SIP-specific Event Notification
Symmetric Response Routing
RFC 3581
An Extension to the Session
Initiation Protocol (SIP) for
Symmetric Response Routing
Multipart type
RFC 4662
A Session Initiation Protocol
(SIP) Event Notification
To/From Header Modification
RFC 4916
Connected Identity in the
Session Initiation Protocol (SIP)
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 security or call charging details.
IMS P-Header Extensions describes the list of supported P-Headers, including links to the relevant
ITEF memorandum where available.
Table 4. IMS P-Header Extensions
AuthorizationHeaderIMS
Defines a new auth-param for the
Authorization header used in REGISTER
requests.
PAccessNetworkInfoHeader
Contains 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.
PAssertedIdentityHeader
Contains an identity resulting from an
authentication process, derived from a SIP
network intermediary. The identity may be
based on SIP Digest authentication.
102
AuthorizationHeaderIMS
Defines a new auth-param for the
Authorization header used in REGISTER
requests.
PAssertedServiceHeader
Contains information used by "trust domains",
according to Spec(T) specifications detailed in
RFC 3324.
PAssociatedURIHeader
Contains 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.
PathHeader
SIP 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.
PCalledPartyIDHeader
Typically 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.
PChargingFunctionAddressesHeader
Contains 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.
PChargingVectorHeader
Contains a unique charging identifier and
correlation information, which is used by
network operators to correctly charge for
routing events through their networks.
PMediaAuthorizationHeader
Contains one or more session-specific media
authorization tokens, which are used for QoS of
the media streams.
PPreferredIdentityHeader
Contains a SIP URI and an optional displayname. For example, "James May"
. 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.
103
AuthorizationHeaderIMS
Defines a new auth-param for the
Authorization header used in REGISTER
requests.
PPreferredServiceHeader
Used by the PAssertedService Header to
determine the preferred user service. Multiple
PPreferreedService headers may be present in a
single request.
PProfileKeyHeader
Contains 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.
PrivacyHeader
Contains values that determine whether
particular header information is deemed as
private by the UA for requests and responses.
PServedUserHeader
Contains 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.
PUserDatabaseHeader
Contains 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).
PVisitedNetworkIDHeader
Contains 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,
SecurityVerifyHeader
Contains information used to negotiate the
security mechanisms between a UAC, and other
SIP entities including UAS, proxy and registrar.
ServiceRouteHeader
Contains 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.
WWWAuthenticateHeaderIms
Extends the WWWAuthenticateResponse header
functionality by defining an additional
authorization parameter (auth-param).
8.8. SIP Servlets - JAIN SLEE Interoperability
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
104
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 5. SIP Servlets / JAIN SLEE Comparison Table
SIP Servlets
JAIN SLEE
Application Architecture
Based on HTTP Servlets. Unit of logic is the SIP
Servlets
Component based, Object Orientated
architecture. Unit of logic is the Service Building
Block
Composition through Application Router
Composition through parent-child relationship
Application State
Servlets are stateless
SBBs may be stateful
Shared state stored in a session and visible to all SBB state is transacted and a property of the SBB
Servlets with access to the session
itself. Shared state may be stored in a separate
ActivityContext via a type safe interface
Concurrency Control
Application managed: use of Java monitors
System Managed: isolation of concurrent
transactions
Facilities (Utilities for Applications)
Timer, Listeners
Timer, Trace, Alarm, Statistics, Profiles.
Protocol Support
SIP, HTTP and Media (JSR 309)Protocol
agnostic.
Consistent event model, regardless of
protocol/resource
Availability Mechanisms
Container managed state (session object) that
can be replicated
Container managed state (SBB CMP, Facility,
ActivityContext) that can be replicated
No transaction context for SIP message
processing
Transaction context for event delivery
Non transacted state operations
Container managed state operations are
transacted
Facilities are non transacted
Facilities, timers, are transacted
No defined failure model
Well defined and understood failure model via
transactions
Management
105
SIP Servlets
JAIN SLEE
No standard management mechanisms defined
JMX 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. 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 Restcomm , 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.
8.9. Eclipse IDE Tools
The SIP Servlets Eclipse tools assist developers in creating JSR-289 applications with Restcomm. You
can use the Dynamic Web Project wizard for converged applications to get started with an empty
project, and then test your application with a real SIP Phone right from the IDE.
Figure 21. SIP Servlets Eclipse IDE Tools
8.9.1. Pre-Install requirements
Eclipse 3.4 is required.
106
8.9.2. Installation
The standard Eclipse update site installation mechanism is leveraged. The Restcomm Update Site is
at the following location: http://mobicents.googlecode.com/svn/downloads/sip-servlets-eclipseupdate-site. After adding this update site to Eclipse you can proceed with the regular Eclipse Plug-in
Installation. If you need help, the process is demonstrated in this video.
8.9.3. SIP Servlets Core Plug-in
This plug-in allows you to create Dynamic Web Projects with the SIP Facet. There are a number of
new Dynamic Web Project configurations for Converged applications. It is best to use the ones
marked as "recommended". After you complete the wizard, a complete converged project skeleton
will be generated. Working with this type of project is similar to working with normal Web projects.
You can see a demo here.
8.9.4. SIP Phone Plug-in
The SIP Phone plug-in integrates a SIP phone inside your Eclipse IDE. You can use the phone to test
your SIP or Media applications. The phone uses the microphone and speakers on your computer
and allows you to simulate real-world scenarios.
107
Chapter 9. Best Practices
This chapter discusses Best Practices related to Restcomm SIP Servlets usage in real world
deployments.
9.1. Restcomm SIP Servlets Performance Tips
Because the default profile of Restcomm SIP Servlets is targeted at a development environment,
some tuning is required to make the server performance suitable for a production environment.
A useful presentation from OKI Japan
9.1.1. Tuning JBoss
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 preferable to have a fast Application Server, most of the information doesn’t apply to
Restcomm . 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.
SIP Servlets Server Logging
9.1.2. Tuning Restcomm SIP Servlets
• Congestion Control: It is recommended that this feature is enabled to avoid overload of the
server and that the sipMessageQueueSize and memoryThreshold parameters are tuned
according to Concurrency and Congestion Control.
• Concurrency : Default Value: None. For better performance, it is recommended to leave this
value set to None.
9.1.3. Tuning The JAIN SIP Stack
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 Configuring SIP Connectors and
Bindings.
• 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.
108
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.
Restcomm 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: 65536.
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.
• gov.nist.javax.sip.MAX_MESSAGE_SIZE=10000
Default value: 10000.
This property controls the maximum size of content that can be read for a SIP Message on UDP.
The default is 65536. The average UDP message size is quite lower than this so reducing this
property will benefit memory usage since a byte buffer of this size is created for every message
received.
It also defines the maximum size of content that a TCP connection can read. Must be at least 4K.
Default is "infinity" — ie. no limit. This is to prevent DOS attacks launched by writing to a TCP
connection until the server chokes.
• gov.nist.javax.sip.TCP_POST_PARSING_THREAD_POOL_SIZE=30
Default value: 30.
Use 0 or do not set this option to disable it. When using TCP, your phones/clients usually connect
independently, creating their own TCP sockets. Sometimes however SIP devices are allowed to
tunnel multiple calls over a single socket. This can also be simulated with SIPP by running "sipp
109
-t t1".
In the stack, each TCP socket has it’s own thread. When all calls are using the same socket they
all use a single thread, which leads to severe performance penalty, especially on multi-core
machines. This option instructs the SIP stack to use a thread pool and split the CPU load between
many threads. The number of the threads is specified in this parameter.
The processing is split immediately after the parsing of the message. It cannot be split before the
parsing because in TCP the SIP message size is in the Content-Length header of the message and
the access to the TCP network stream has to be synchronized.
Additionally, in TCP the message size can be larger. This causes most of the parsing for all calls
to occur in a single thread, which may have impact on the performance in trivial applications
using a single socket for all calls. In most applications it doesn’t have performance impact. If the
phones/clients use separate TCP sockets for each call, this option doesn’t have much impact,
except the slightly increased memory footprint caused by the thread pool. It is recommended to
disable this option in this case by setting it 0 or not setting it at all. You can simulate multi-socket
mode with "sipp -t t0". With this option also we avoid closing the TCP socket when something
fails, because we must keep processing other messages for other calls. Note: This option relies
on accurate Content-Length headers in the SIP messages. It cannot recover once a malformed
message is processed, because the stream iterator will not be aligned any more. Eventually the
connection will be closed.
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.
9.1.4. Tuning The JVM
The following tuning information applies to Sun JDK 1.6, however the information should also
apply to Sun JDK 1.5.
For more information on tuning Restcomm SIP Servlets performance, refer to the
OKI Japan Presentation.
For more information on performance, refer to the Performance White Paper.
To
pass
arguments
to
the
JVM,
change
$JBOSS_HOME/bin/standalone.conf
(Linux)
or
$JBOSS_HOME/bin/standalone.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
110
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.
9.1.5. Tuning The Operating System
The following tuning information is provided for Red Hat Enterprise Linux (RHEL) servers that are
running high-load configurations. The tuning information should also apply to other Linux
distributions.
After you have configured RHEL with the tuning information, you must restart the operating
system. You should see improvements in I/O response times. With SIP, the performance
improvement can be as high as 20%.
• Large Memory Pages
Setting large memory pages can reduce CPU utilization by up to 5%.
Ensure that the option `-XX:+UseLargePages` is passed and ensure that the following Java
HotSpot™ Server VM warning does not occur:
Failed to reserve shared memory (errno = 22)" when starting JBoss. It means that the number
of pages at OS level is still not enough.
To learn more about large memory pages, and how to configure them, refer to Java Support for
Large Memory Pages and Andrig’s Miller blog post.
• Network buffers
You can increase the network buffers size by adding the following lines to your /etc/sysctl.conf
file:
• net.core.rmem_max = 16777216
• net.core.wmem_max = 16777216
• net.ipv4.tcp_rmem = 4096 87380 16777216
• net.ipv4.tcp_wmem = 4096 65536 16777216
• net.core.netdev_max_backlog = 300000
• Execute the following command to set the network interface address:
sudo ifconfig [eth0] txqueuelen 1000 #
111
Replace [eth0] with the correct name of the actual network interface you are setting up.
9.2. NAT Traversal
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.
9.2.1. STUN
STUN (Session Traversal Utilities for NAT) is not generally considered a viable solution for
enterprises because STUN cannot be used with symmetric NATs.
Most enterprise-grade firewalls are symmetric, therefore STUN support must be provided in the SIP
Clients themselves.
Most of the proxy and media gateways installed by VoIP providers recognize the public IP address
the packets have originated from. When both SIP end points are behind a NAT, they can act as
gateways to clients behind NAT.
9.2.2. TURN
TURN (Traversal Using Relay NAT) is an IETF standard, which implements media relays for SIP endpoints. The standard overcomes the problems of clients behind symmetric NATs which cannot rely
on STUN to solve NAT traversal.
TURN connects clients behind a NAT to a single peer, providing the same protection offered by
symmetric NATs and firewalls. The TURN server acts as a relay; any data received is forwarded.
This type of implementation is not ideal. It assumes the clients have a trust relationship with a
TURN server, and a request session allocation based on shared credentials.
This can result in scalability issues, and requires changes in the SIP clients. It is also impossible to
determine when a direct, or TURN, connection is appropriate.
9.2.3. ICE
ICE (Interactive Connection Establishment) leverages both STUN and TURN to solve the NAT
traversal issues.
It allows devices to probe for multiple paths of communication, by attempting to use different port
numbers and STUN techniques. If ICE support is present in both devices, it is quite possible that the
devices can initiate and maintain communication end-to-end, without any intermediary media
relay.
Additionally, ICE can detect cases where direct communication is impossible and automatically
initiate fall-back to a media relay.
112
ICE is not currently in widespread use in SIP devices, because ICE capability must be embedded
within the SIP devices.
Depending on the negotiated connection, a reINVITE may be required during a session, which adds
more load to the SIP network and more latency to the call.
If the initiating ICE client attempts to call a non-ICE client, then the call setup-process will revert to
a conventional SIP call requiring NAT traversal to be solved by other means.
9.2.4. Other Approaches
While the above is a good solution to circumvent NAT issues. There might be cases where it is not
possible to use those solutions at all.
Other approaches include using proxy and media that can act as gateways, Session Border
Controllers, enhanced Firewall with Application Layer Gateway (ALG) and Tunnelling.
Here is more information on Session Border Controllers and how they can resolve NAT issues when
above solutions are not possible
113
Chapter 10. Apendix
10.1. Java Development Kit (): Installing, Configuring
and Running
The [app]` Platform` is written in Java; therefore, before running any server, you must have a
working Java Runtime Environment () or Java Development Kit () installed on your system. In
addition, the JRE or JDK you are using to run [app] must be version 5 or higher [1: At this point
in time, it is possible to run most 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 web site, forums or discussion pages if you need to inquire about the
status of running the XML Document Management Server with Java 6.].
10.1.1. JRE versus JDK - 32-Bit versus 64-Bit
Should I Install the JRE or JDK?
Although you can run
servers using the Java Runtime Environment, we assume that most users
are developers interested in developing Java-based, [app]-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.
10.1.2. Downloading JDK
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 `" (where [replaceable]` 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
114
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 selfextracting file (for example, jdk-1_5_0_16-linux-i586-rpm.bin), and the other is merely a selfextracting 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 selfextracting 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 [app]`` in a production environment.
Installing
The following procedures detail how to install the Java Development Kit on both Linux and
Windows.
Procedure: Installing the JDK on Linux
1. Regardless of which file you downloaded, you can install it on Linux by simply making sure the
file is executable and then running it:
~]$ chmod +x "jdk-1_5_0_-linux--rpm.bin"
~]$ ./"jdk-1_5_0_-linux--rpm.bin"
Moving from Non-RPM Installer to SysV Service Scripts
If you download the non-RPM self-extracting file (and installed it), and you are
running on an RPM-based system, you can still set up the SysV service scripts by
downloading and installing one of the -compat packages from the JPackage
project. Remember to download the -compat package which corresponds correctly
to the minor release number of the JDK you installed. The compat packages are
available
from
link:ftp://jpackage.hmdc.harvard.edu/JPackage/1.7/generic/RPMS.non-free/.
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.
10.1.3. Installing JDK on Windows
1. Using Explorer, simply double-click the downloaded self-extracting installer and follow the
instructions to install the JDK.
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.
115
10.1.4. Setting Linux JAVA_HOME Environment Variables
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.
10.1.5. Setting the Correct Java Version
Setting java, javac and java_sdk_1.5.0 Using the alternatives command
As the root user, call /usr/sbin/alternatives with the --config java option to select between
JDKs and JREs installed on your system:
10.1.6. Setting JAVA_HOME Environment Variables on Windows
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.
10.1.7. Uninstalling JDK on Linux and Windows
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 `
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.
10.1.8. Setting the JBOSS_HOME Environment Variable
The [app]` Platform` (`) is built on top of the [app]`JBoss Application Server (JBoss AS). You do
not need to set the JBOSS_HOME environment variable to run any of the [app]` 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
~]$ echo $JBOSS_HOME
116
$JBOSS_HOME to see if it is currently defined in your environment:
The [app]` Platform` and most &PLATFORM_NAME; servers are built on top of the JBoss
Application Server (JBoss AS). When the [app]` Platform` or &PLATFORM_NAME; servers are built
from source, then JBOSS_HOME must be set, because the &PLATFORM_NAME; 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 &PLATFORM_NAME; files.
This guide does not detail building the [app]` Platform` or any &PLATFORM_NAME; servers from
source. It is nevertheless useful to understand the role played by JBoss AS and JBOSS_HOME in the
&PLATFORM_NAME; 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
Even if you fall into the category below of not needing to set JBOSS_HOME, you may
want to for various reasons anyway. Also, even if you are instructed that you do
not need to set JBOSS_HOME, it is good practice nonetheless to check and make sure
that JBOSS_HOME actually isn’t set or defined on your system for some reason. This
can save you both time and frustration.
You DO NOT NEED to set JBOSS_HOME if…
• …you have installed the [app]` Platform` binary distribution.
• …you have installed a &PLATFORM_NAME;server binary distribution which bundles JBoss AS.
You MUST set JBOSS_HOME if…
• …you are installing the [app]` Platform` or any of the &PLATFORM_NAME; servers from source.
• …you are installing the [app]` Platform` binary distribution, or one of the &PLATFORM_NAME;
server binary distributions, which do not bundle JBoss AS.
Naturally, if you installed the [app]` Platform` or one of the &PLATFORM_NAME; 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 [app]` Platform` or individual &PLATFORM_NAME; 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: 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
117
your system:
export JBOSS_HOME="/home////"
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: 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.].
~]$ source ~/.bashrc
4. Finally, ensure that JBOSS_HOME is set in the current session, and actually points to the correct
location:
The command line usage below is based upon a binary installation of the
[app]` Platform`. In this sample output, JBOSS_HOME has been set correctly to
the topmost_directory of the installation. Note that if you are installing
one of the standalone [app] servers (with JBoss AS bundled!), then JBOSS_HOME
would point to the topmost_directory of your server installation.
~]$ echo $JBOSS_HOME
/home/silas/
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 &PLATFORM_NAME;Platform or individual &PLATFORM_NAME;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.
10.1.9. Setting CATALINA_HOME on Linux and Windows
Procedure: Setting the CATALINA_HOME Environment Variable on Linux
1. The CATALINA_HOME environment variable must point to the location of your Tomcat installation.
Any &PLATFORM_NAME; 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 &PLATFORM_NAME; 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
118
file, taking care to substitute for the topmost directory of the &PLATFORM_NAME;
server you installed:
export CATALINA_HOME="/home////"
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
Procedure: Setting the CATALINA_HOME Environment Variable on Windows
1. The CATALINA_HOME environment variable must point to the location of your Tomcat installation.
Any &PLATFORM_NAME; 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 &PLATFORM_NAME; server installation.
If you are planning on running the Tomcat container as the Administrator, then you should, of
course, set the CATALINA_HOME environment variable as the administrator, and if you planning to
run Tomcat as a normal user, then set CATALINA_HOME as a user environment variable.
For
information
on
how
to
set
environment
variables
in
Windows,
refer
to
http://support.microsoft.com/kb/931715.
119
Chapter 11. JSR 289 Errata
This chapter discusses deviations from the JSR 289 specification by Restcomm SIP Servlets after
feedback on usage in real world deployments and from the community.
11.1. Restcomm SIP Servlets Deviations from JSR 289
• _Correlation of Responses to Proxy Branches _: It seems the javadoc for Speed Dial contains an
error, SipServlet.doBranchResponse() shouldn’t be included as it contradicts the last sentence
from the spec 10.2.4.2 Correlating responses to proxy branches : "Note that if the
doBranchResponse() is not overridden then doResponse() method will be invoked only for the
best final response as before",
If SipServlet.doBranchResponse() handling is done in
SipServlet.doResponse() and the servlet overrides SipServlet.doResponse() then it will receive
intermediate final responses
as well as the best final response which is not the desired
behavior, so the doBranchResponse() handling is done in SipServlet.doService() method
allowing applications not overriding doResponse or doService to receive both intermediate
final responses on the doBranchResponse as well as the best final response on doResponse but
this fixes the issue of intermediate final responses being delivered to doResponse in case the
servlet overrides it.
• SipServletResponse typo : _ SipServletResponse.SC_TEMPORARLY_UNAVAILABLE_
replaced by SC_TEMPORARILY_UNAVAILABLE.
120
should be
Source Exif Data:
File Type : PDF File Type Extension : pdf MIME Type : application/pdf PDF Version : 1.4 Linearized : No Page Count : 122 Page Mode : UseOutlines Title : Restcomm SIP Servlets User Guide Creator : Asciidoctor PDF 1.5.0.alpha.11, based on Prawn 1.3.0 Producer : Asciidoctor PDF 1.5.0.alpha.11, based on Prawn 1.3.0 Create Date : 2017:09:20 02:43:06+01:00 Modify Date : 2017:09:20 02:43:06+01:00EXIF Metadata provided by EXIF.tools