Chapter 2. SIP Servlets Server-Installing, Configuring and Running

2.1. SIP Servlet-Enabled JBoss Application Server: Installing, Configuring and Running

You can run the Mobicents SIP Servlets Server on top of either the JBoss Application Server or the Tomcat Servlet Container. This section details how to install the SIP Servlets Server on top of the JBoss Application Server. If you would rather run the SIP Servlets Server on top of the Tomcat Servlet Container, go to Section 2.2, “SIP Servlet-Enabled Tomcat Servlet Container: Installing, Configuring and Running”^[3]

Differences Between a Standard JBoss Installation and One Customized for Mobicents SIP Servlets

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

The server/default/deploy directory contains both HTTP and SIP Servlet applications (WAR and SAR2 files).
The server/default/deploy/jboss-web.deployer unit has been modified to provide extended classes to the standard JBoss container classes, in order to allow SIP applications to be loaded and the SIP stack to be started.
The server/default/deploy/jboss-web.deployer/context.xml file has been modified to provide the extended manager to be able to manage SIP sessions and SIP application sessions in addition to HTTP sessions.
The server/default/deploy/jboss-web.deployer/META-INF/jboss-service.xml file and the server/default/deploy/jboss-web.deployer/META-INF/webserver-xmbean.xml file have been modified so that it is now possible for JBoss containers to correctly deploy SIP servlets and converged applications.
A dars directory containing all of the Default Application Router (DAR) properties files for using the various SIP Servlets applications (which come bundled with the release) has been added to the server/default/conf directory.
Additional JAR files have been added to enable SIP Servlet functionality; these can be seen in the server/default/deploy/jboss-web.deployer/ directory.

Installing the Java Development Kit

2.1.1. Java Development Kit: Installing, Configuring and Running

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

Should I Install the JRE or JDK?

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

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

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

Wider datapath: the pipe between RAM and CPU is doubled, which improves the performance of memory-bound applications when using a 64-bit JVM.
64-bit memory addressing gives virtually unlimited (1 exabyte) heap allocation. However large heaps affect garbage collection.
Applications that run with more than 1.5 GB of RAM (including free space for garbage collection optimization) should utilize the 64-bit JVM.
Applications that run on a 32-bit JVM and do not require more than minimal heap sizes will gain nothing from a 64-bit JVM. Barring memory issues, 64-bit hardware with the same relative clock speed and architecture is not likely to run Java applications faster than their 32-bit cousin.

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

Downloading

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

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

Installing

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

Procedure 2.1. Installing the JDK on Linux

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_<minor_version>-linux-<architecture>-rpm.bin"
~]$ ./"jdk-1_5_0_<minor_version>-linux-<architecture>-rpm.bin"

You Installed Using the Non-RPM Installer, but Want the 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 ftp://jpackage.hmdc.harvard.edu/JPackage/1.7/generic/RPMS.non-free/.

Important

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

Procedure 2.2. Installing the JDK on Windows

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.

Setting the JAVA_HOME Environment Variable on Generic Linux

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

Setting the `JAVA_HOME` Environment Variable on Linux

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

~]$ echo $JAVA_HOME

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

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

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

Setting java, javac and java_sdk_1.5.0 Using the alternatives command

Selecting the Correct System JVM on Linux using `alternatives`

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

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

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

There are 3 programs which provide 'java'.

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


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

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

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

~]$ /usr/sbin/alternatives --config javac

~]$ /usr/sbin/alternatives --config java_sdk_1.5.0

Setting the JAVA_HOME Environment Variable on Windows

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

Testing

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

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

Uninstalling

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

Uninstalling the JDK on Linux

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

Uninstalling the JDK on Windows

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

2.1.2. Pre-Install Requirements and Prerequisites

Hardware Requirements

Sufficient Disk Space: You must have sufficient disk space in order to install the MSS for JBoss binary release. Once unzipped, version 0.7.2 of the MSS for JBoss binary release requires at least 120 MB of free disk space. Keep in mind that disk space requirements may change from release to release.
Anything Java Itself Will Run On: MSS for JBoss is 100% Java. It will run on the same hardware that the JBoss Application Server runs on.

Software Prerequisites

JDK 5 or Higher

2.1.3. Downloading

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

2.1.4. Installing

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

Use Version Numbers Relevant to Your Installation!

For clarity, the command line instructions presented in this chapter use specific version numbers and directory names. Remember to replace them with version numbers and file names relevant to those you are actually working with.

Procedure 2.3. Installing the MSS for JBoss Binary Distribution on Linux

For this example, we'll assume you're currently in your home directory, which is where you downloaded the zip file to. First, create a subdirectory to hold the unzipped MSS for JBoss files. It is good practice to include the version number in this directory name; if you do so, remember to correctly match it with the version of the MSS for JBoss distribution you downloaded.
```
~]$ mkdir "mss-jboss-<version>"
```

Move the downloaded zip file into the directory you just created:

~]$ mv "mss-0.7.2-jboss-4.2.3.GA-0901261304.zip" "mss-jboss-<version>"

Move into that directory:
```
~]$ cd "mss-jboss-<version>"
```
Finally, use Java's jar -xvf command to extract the contents of the zip file into the current directory, thus completing the install:
```
mss-jboss-<version>]$ jar -xvf "mss-0.7.2-jboss-4.2.3.GA-0901261304.zip"
```
- Alternatively, if Linux's unzip utility is present on your system or is installable, you can use it in lieu of Java's jar -xvf command:
```
mss-jboss-<version>]$ unzip "mss-0.7.2-jboss-4.2.3.GA-0901261304.zip"
```
  Note
  You can also use unzip's -d<unzip_to_location> option to extract the zip file's contents to a location other than the current directory.
To free disk space, you may want to delete the zip file once you've extracted its contents:
```
mss-jboss-<version>]$ rm "mss-0.7.2-jboss-4.2.3.GA-0901261304.zip"
```

Procedure 2.4. Installing the MSS for JBoss Binary Distribution on Windows

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 subfolder in My Downloads to extract the zip file's contents into. When you name this folder, it is good practice to include the version number; if you do so, remember to correctly match it with the version of the MSS for JBoss binary distribution you downloaded. In these instructions, we will refer to this folder as mss-jboss-<version>.
Double-click the downloaded zip file, selecting as the destination folder the one you just created to hold the zip file's contents.
- 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 downloaded zip file from My Downloads to the folder that you just created to hold the SIP Servlets Server files.
- 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 Open Command Window Here 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:\Users\Me>cd "My Downloads\mss-jboss-<version>"
```
- Finally, use the jar -xvf command to extract the archive contents into the current folder.
```
C:\Users\Me\My Downloads\mss-jboss-<version>>jar -xvf "mss-0.7.2-jboss-4.2.3.GA-0901261304.zip"
```
At this point, you may want to move the folder holding the MSS for JBoss files (in this example, the folder named mss-jboss-<version>) to another location. This step is not strictly necessary, but it is probably a good idea to move the installation folder from My Downloads to a user-defined location for storing runnable programs. Any location will suffice, however.
You may also want to delete the zip file after extracting its contents in order to free disk space:
```
C:\Users\Me\My Downloads\mss-jboss-<version>>delete "mss-0.7.2-jboss-4.2.3.GA-0901261304.zip"
```

2.1.5. Setting the JBOSS_HOME Environment Variable

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

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

Alternatively, after having set JBOSS_HOME, you can simply run your MSS for JBoss server now and return to this section to configure it later.

2.1.5.1. Setting the JBOSS_HOME Environment Variable

The JBoss Communications Platform (JBCP) is built on top of the JBoss Enterprise Application Platform (JBoss EAP). You do not need to set the JBOSS_HOME environment variable to run any of the JBoss Communications 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 Linux

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

~]$ echo $JBOSS_HOME

Silence on the command line (a completely blank line) means that it is not set, in which case you can proceed with running the JBoss Communications Platform.

Checking to See if JBOSS_HOME is Set on Windows

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

If JBOSS_HOME is already set on your system, then you have three options:

unset it, which only takes effect for the current session and is therefore not advised;
find where JBOSS_HOME is defined, such as in your local ~/.bashrc startup script in Linux, or, possibly, system-wide in /etc/bashrc, and remove it or comment it out;
or point it to the correct location, in which case you should refer to the following instructions on how to set JBOSS_HOME.

Setting the JBOSS_HOME Environment Variable on Linux

The JBOSS_HOME environment variable must point to the directory which contains all of the files for the JBoss Communications Platform 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 Linux, it is possible to set JBOSS_HOME as a system-wide environment variable, by defining it in /etc/bashrc, but this method is neither recommended nor detailed in these instructions.

Procedure 2.5. To Set JBOSS_HOME on Linux...

Open the ~/.bashrc startup script, which is a hidden file in your home directory, in a text editor, and insert the following line on its own line while substituting for the actual install location on your system:
```
export JBOSS_HOME="/home/<username>/<path>/<to>/<install_directory>"
```
Save and close the .bashrc startup script.
You should source the .bashrc script to force your change to take effect, so that JBOSS_HOME becomes set for the current session^[5].
```
~]$ source ~/.bashrc
```
Finally, ensure that JBOSS_HOME is set in the current session, and actually points to the correct location:
Note
The command line usage below is based upon a binary installation of the JBoss Communications Platform. In this sample output, JBOSS_HOME has been set correctly to the topmost_directory of the JBCP installation. Note that if you are installing one of the standalone JBCP servers (with JBoss AS bundled!), then JBOSS_HOME would point to the topmost_directory of your server installation.
```
~]$ echo $JBOSS_HOME
/home/silas/jboss-eap-4.3/jboss-as
```

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 JBoss Communications Platform 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.

2.1.6. Configuring

To configure MMS for JBoss, refer to Section 2.3, “Configuring”.

2.1.7. Running

Once installed, you can run MSS for JBoss 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 the JBoss Application Server 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 server started successfully if the last line of output is similar to the following (ending with “Started in 23s:648ms”):

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

Detailed instructions are given below, arranged by platform.

Procedure 2.6. Running MSS for JBoss on Linux

Change your working directory to MSS for JBoss's topmost directory (the one in which you extracted the zip file's contents to):
```
downloads]$ cd "mss-jboss-<version>"
```
(Optional) Ensure that the bin/run.sh start script is executable:
```
mss-jboss-<version>]$ chmod +x bin/run.sh
```
Finally, execute the run.sh Bourne shell script:
```
mss-jboss-<version>]$ ./bin/run.sh
```
- Instead of executing the Bourne shell script to start the server, you may alternatively run the run.jar executable Java archive in the bin directory:
```
mss-jboss-<version>]$ java -jar bin/run.jar
```

Procedure 2.7. Running MSS for JBoss on Windows

There are several ways to start MSS for JBoss 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 subfolder.
Although not the preferred way (see below), it is possible to start MSS for JBoss by double-clicking on the run.bat executable batch file.
- As mentioned above, the best way to start MSS for JBoss 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 <topmost_directory>\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 "mss-jboss-<version>"
```
- Start the JBoss Application Server by running the executable run.bat batch file:
```
C:\Users\Me\My Downloads\mss-jboss-<version>>bin\run.bat
```
  - It is also possible to start the server by running the run.jar executable Java archive:
```
C:\Users\Me\My Downloads\mss-jboss-<version>>java -jar bin\run.jar
```

2.1.8. Using

Once the server is running, you can access the SIP Servlets Management Console by opening your browser and navigating to http://localhost:8080/sip-servlets-management/.

2.1.9. Stopping

Detailed instructions for stopping the JBoss Application Server 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:

[Server] Shutdown complete
Shutdown complete
Halting VM

Procedure 2.8. Stopping MSS for JBoss on Linux by Executing `shutdown.sh` or `shutdown.jar`

You can shut down the JBoss Application Server by executing the shutdown.sh Bourne shell script in the <topmost_directory>/bin directory. To do so, first change your working directory to the binary distribution's topmost directory (the one to which you extracted the downloaded zip file's contents):
```
downloads]$ cd "mss-jboss-<version>"
```
(Optional) Ensure that the bin/shutdown.sh start script is executable:
```
mss-jboss-<version>]$ chmod +x bin/shutdown.sh
```
Finally, run the shutdown.sh executable Bourne shell script, and remember to add the -S option (which is the short option for --shutdown) as a command line argument:
```
mss-jboss-<version>]$ ./bin/shutdown.sh -S
```
- Instead of executing the Bourne shell script to stop the server, you may alternatively run the shutdown.jar executable Java archive to do so (and remembering, again, to add the -S command line argument):
```
mss-jboss-<version>]$ java -jar bin/shutdown.jar -S
```

Procedure 2.9. Stopping MSS for JBoss on Windows

Stopping the JBoss Application Server on Windows consists in executing either the shutdown.bat or the shutdown.jar executable file in the bin subfolder of the MSS for JBoss binary distribution. Make sure to add the -S option (which is the short option for --shutdown) as a command line argument.
```
C:\Users\Me\My Downloads\mss-jboss-<version>>bin\shutdown.bat -S
```
- Alternatively, you can execute the shutdown.jar Java archive by running the java -jar command, and remembering to add the -S option as a command line argument:
```
C:\Users\Me\My Downloads\mss-jboss-<version>>java -jar bin\shutdown.jar -S
```

2.1.10. Uninstalling

To uninstall MSS for JBoss, simply delete the directory you decompressed the binary distribution archive into.

^[3] Keep in mind that not all capabilities enjoyed by MSS for JBoss are available for MSS for Tomcat.

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

^[5] 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.