JBoss.orgCommunity Documentation
The Mobicents Media Server is available in both binary and source code distributions. The simplest way to get started with the Media Server is to download the ready-to-run binary distribution. Alternatively, the source code for the Mobicents Media Server can be obtained by checking it out from its repository using the Subversion version control system ( SVN ), and then built using the Maven build system. Whereas installing the binary distribution is recommended for most users, obtaining and building the source code is recommended for those who want access to the latest revisions and Media Server capabilities.
The Mobicents platform is written in Java. A working Java Runtime Environment (JRE) or Java Development Kit (JDK) must be installed prior to running the server. The required version must be version 5 or higher.
It is possible to run most Mobicents servers, such as the JAIN SLEE Server, using a Java 6 JRE or JDK.
Although Mobicents servers are capable of running on the Java Runtime Environment, this guide assumes the audience is mainly developers interested in developing Java-based, Mobicents-driven solutions. Therefore, installing the Java Development Kit is covered due to the anticipated audience requirements.
If the system uses 64-Bit Linux or Windows architecture, the 64-bit JDK is strongly recommended over the 32-bit version. The following heuristics should be considered in determining whether the 64-bit Java Virtual Machine (JVM) is suitable:
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 provides a virtually unlimited (1 exabyte) heap allocation. Note that large heaps can 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. Excluding memory issues, 64-bit hardware with the same relative clock speed and architecture is not likely to run Java applications faster than the 32-bit version.
The following instructions describe how to download and install the 32-bit JDK, however the steps are nearly identical for installing the 64-bit version.
Download the Sun JDK 5.0 (Java 2 Development Kit) from Sun's website: http://java.sun.com/javase/downloads/index_jdk5.jsp. Click the Download link next to "JDK 5.0 Update <x>
" (where <x>
is the latest minor version release number).
The Sun website offers two download options:
A self-extracting RPM (for example, jdk-1_5_0_16-linux-i586-rpm.bin
)
A self-extracting file (e.g. jdk-1_5_0_16-linux-i586.bin
)
If installing the JDK on Red Hat Enterprise Linux, Fedora, or another RPM-based Linux system, it is recommended that the self-extracting file containing the RPM package is selected. This option will set up and use the SysV service scripts in addition to installing the JDK. The RPM option is also recommended if the Mobicents platform is being set up in a production environment.
The following procedures detail how to install the Java Development Kit on both Linux and Windows.
Procedure 2.1. Installing the JDK on Linux
Ensure the file is executable, then run it:
~]$ chmod +x "jdk-1_5_0_<minor_version>-linux-<architecture>-rpm.bin" ~]$ ./"jdk-1_5_0_<minor_version>-linux-<architecture>-rpm.bin"
If the non-RPM self-extracting file is selected for an RPM-based system, the SysV service scripts can be configured by downloading and installing one of the -compat
packages from the JPackage project. Download the -compat
package that corresponds correctly to the minor release number of the installed JDK. The compat packages are available from ftp://jpackage.hmdc.harvard.edu/JPackage/1.7/generic/RPMS.non-free/.
A -compat
package is not required for RPM installations. The -compat
package 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, double-click the downloaded self-extracting installer and follow the instructions to install the JDK.
Configuring the system for the JDK consists of two tasks: setting the JAVA_HOME
environment variable, and ensuring the system is using the proper JDK (or JRE) using the alternatives
command. Setting JAVA_HOME
generally overrides the values for java
, javac
and java_sdk_1.5.0
in alternatives
, however it is recommended to specify the value for consistency.
JAVA_HOME
Environment Variable on Generic Linux
After installing the JDK, ensure the JAVA_HOME
environment variable exists and points to the location of the JDK installation.
JAVA_HOME
Environment Variable on LinuxDetermine whether JAVA_HOME
is set by executing the following command:
~]$ echo $JAVA_HOME
If JAVA_HOME
is not set, the value must be set to the location of the JDK installation on the system. This can be achieved by adding two lines to the ~/.bashrc
configuration file. Open ~/.bashrc
(or create it if it does not exist) and add a line similar to the following one anywhere inside the file:
export JAVA_HOME="/usr/lib/jvm/jdk1.5.0_<version>"
The changes should also be applied for other users who will be running the Mobicents on the machine (any environment variables export
ed from ~/.bashrc
files are local to that user).
java
, javac
and java_sdk_1.5.0
using the alternatives
command alternatives
On systems with the alternatives
command, including Red Hat Enterprise Linux and Fedora, it is possible to choose which JDK (or JRE) installation to use, as well as which java
and javac
executables should be run when called.
As the superuser, call /usr/sbin/alternatives
with the --config java
option to select between JDKs and JREs installed on your system:
home]$ sudo /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:
The Sun JDK, version 5, is required to run the java
executable. In the alternatives
information printout above, a plus (+
) next to a number indicates the option currently being used. Press Enter to keep the current JVM, or enter the number corresponding to the JVM to select that option.
As the superuser, repeat the procedure above for the javac
command and the java_sdk_1.5.0
environment variable:
home]$ sudo /usr/sbin/alternatives --config javac
home]$ sudo /usr/sbin/alternatives --config java_sdk_1.5.0
JAVA_HOME
Environment Variable on WindowsFor information on how to set environment variables in Windows, refer to http://support.microsoft.com/kb/931715.
To ensure the correct JDK or Java version (5 or higher), and that the java executable is in the PATH
environment variable, run the java -version
command in the terminal from the home directory:
home]$ 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)
It is not necessary to remove a particular JDK from a system, because the JDK and JRE version can be switched as required using the alternatives
command, and/or by setting JAVA_HOME
.
On RPM-based systems, uninstall the JDK using the yum remove <jdk_rpm_name>
command.
On Windows systems, check the JDK entry in the Start
menu for an uninstall option, or use Add/Remove Programs
.
This section details how to install the Mobicents Media Server.
Ensure that the following requirements have been met before continuing with the install.
The latest version of the Media Server is
available from
http://www.mobicents.org/mms/mms-downloads.html
. The top row of the table holds the latest version.
Click the
Download
link to start the download.
Once the requirements and prerequisites have been met, the Media Server can be installed onto the system. Follow the instructions below for the operating system on which the server will reside.
For clarity, the command line instructions presented in this chapter use specific version numbers and directory names. Ensure this information is substituted with the binary distribution's version numbers and file names.
Procedure 2.3. Installing the Media Server Binary Distribution on Linux
It is assumed that the downloaded archive is saved in the home directory, and that a terminal window is open displaying the home directory.
Create a subdirectory to extract the files into. For ease of identification, it is recommended that the version number of the binary is included in this directory name.
~]$ mkdir “ms-<version>
”
Move the downloaded zip file into the directory:
~]$ mv “mms-standalone-2.0.0.GA.zip” “ms-<version>
”
Move into the directory:
~]$ cd “ms-<version>
”
Extract the files into the current directory by executing one of the following commands.
Java:
ms-<version>
]$ jar -xvf “mms-standalone-2.0.0.GA.zip”
Linux:
ms-<version>]$unzip "mms-standalone-2.0.0.GA.zip"
Alternatively, use
unzip
-d <unzip_to_location> to extract
the zip file's contents to a location
other than the current directory.
Consider deleting the archive, if free disk space is an issue.
ms-<version>
]$ rm “mms-standalone-2.0.0.GA.zip”
Procedure 2.4. Installing the Media Server Binary Distribution on Windows
For this procedure, it is assumed that the
downloaded archive is saved in the
My Downloads
folder.
Create a subfolder 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,
ms-<version>
.
Extract the contents of the archive, specifying the destination folder as the one created in the previous step.
Alternatively, execute the
jar -xvf
command to extract the binary distribution files
from the zip archive.
Move the downloaded zip file from
My Downloads
to the folder created in the previous
step.
Open the Windows Command Prompt and
navigate to the folder that contains the
archive using the
cd
command
Execute the
jar -xvf
command to extract the archive contents
into the current folder.
C:Users<user>My Downloadsms-<version>jar -xvf "mms-standalone-2.0.0.GA.zip"
It is recommended that the folder holding the Media Server files (in this example, the folder named mms-standalone-
) is moved to a user-defined location for storing executable programs. For example, the <version>
Program Files
folder.
Consider deleting the archive, if free disk space is an issue.
C:Users<user>My Downloadsms-<version>delete "mms-standalone-2.0.0.GA.zip"
In the Linux terminal or Windows command prompt, the Standalone Media Server has started successfully if the last line of output is similar to the following
2100 [main] INFO org.mobicents.media.server.bootstrap.MainDeployer - [[[[[[[[[ Mobicents Media Server: release.version=2.0.0.GA Started ]]]]]]]]]
Procedure 2.5. Running the Media Server on Linux
Change the working directory to installation directory (the one in which the zip file's contents was extracted to)
downloads]$ cd "mms-standalone-<version>"
(Optional) Ensure that the
bin/run.sh
start script is executable.
ms-<version>]$ chmod +x bin/run.sh
Execute the
run.sh
Bourne shell script.
ms-<version>]$ ./bin/run.sh
Instead of executing the Bourne shell script to
start the server, the
run.jar
executable Java archive can be executed from the
bin
directory:
mms-standalone-<version>]$ java -jar bin/run.jar
Procedure 2.6. Running the Media Server on Windows
Using Windows Explorer, navigate to the
bin
subfolder in the installation directory.
The preferred way to start the Media Server is 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<user>My Downloads>cd "mms-standalone-<version>"
Start the Server by executing one of the following files:
run.bat
batch file:
C:Users<user>My Downloadsmms-standalone<version>>binrun.bat
run.jar
executable Java archive:
C:Users<user>My Downloadsmms-standalone-<version>>java -jar binrun.jar
Using run.sh
without any arguments binds the server at 127.0.0.1
. To bind server to different ip, pass the ip address as value to -b
command line option. For example to bind the server to 115.252.103.220
ms-<version>]$ ./bin/run.sh -b 115.252.103.220
The run
script supports the following options:
usage: run.sh [options] -h, --help Show help message -b, --host=<host or ip> Bind address for media server.
Detailed instructions for stopping the Media Server are given below, arranged by platform. If the server is correctly stopped, the following three lines are displayed as the last output in the Linux terminal or Command Prompt:
[Server] Shutdown complete Shutdown complete Halting VM
Procedure 2.7. Stopping the Standalone Media Server on Linux
Change the working directory to the binary distribution's install directory.
~]$ cd "mms-standalone-<version>"
(Optional) Ensure that the bin/shutdown.sh start script is executable:
mms-standalone-<version>]$ chmod +x bin/shutdown.sh
Run the
shutdown.sh
executable Bourne shell script with the
-S
option (the short option for
--shutdown
) as a command line argument:
mms-standalone-<version>]$./bin/shutdown.sh -S
Procedure 2.8. Stopping Standalone Media Server on Windows
Stopping the Standalone Media Server on Windows
consists of executing either the
shutdown.bat
or the
shutdown.jar
executable file in the
bin
subfolder of the MMS for JBoss binary
distribution. Ensure the
-S
option (the short option for
--shutdown
) is included in the command line argument.
C:Users<user>My Downloadsmms-standalone-<version>>binshutdown.bat -S
The
shutdown.jar
executable Java archive with the
-S
option can also be used to shut down the
server:
C:Users<user>My Downloadsmms-standalone-<version>>java -jar binshutdown.jar -S
Now the server is installed, it is important to understand the layout of the server directories. An understanding of the server structure is useful when deploying examples, and making configuration changes. It is also useful to understand what components can be removed to reduce the server boot time.
The directory structure in the Standalone Media Server installation directory is named using a standard structure. Table 2.1, “Directory Structure” describes each directory, and the type of information contained within each location.
Table 2.1. Directory Structure
Directory Name | Description |
---|---|
bin | All the entry point JARs and start scripts included with the Media Server distribution are located in the bin directory |
conf | The conf directory contains the bootstrap descriptor, bootstrap-beans.xml by default, file for a given server configuration. This defines the core services that are fixed for the lifetime of the server. It also contains the log4j.xml that defines the logging filter. |
deploy | The deploy directory is the default location the deployment service looks to at start time for deployment content. This may be overridden through the MainDeployer's path attribute. |
lib | Contains the startup JAR files used by the server. |
log |
Contains the logs from the bootstrap
logging service. The
log
directory is the default directory into
which the bootstrap logging service
places its logs, however, the location
can be overridden by altering the
log4j.xml configuration file. This file
is located in the
/conf
directory. log directory is created automatically when the server is started.
|
mbrola |
Contains the MBROLA binary and voices. The available voices are
The available MBROLA voices are
Please note that MBROLA is not LGPL model. To understand license please look at http://tcts.fpms.ac.be/synthesis/mbrola/mbrlicen.html In addition to MBROLA, the free voices available are Free Voice
|
media | The default directory for media files. The MediaPlayer, Recorder etc components uses media directory as default directory to read from/write and play/record media files. |
temp |
temp is created automatically when the server is started.
The MainDeployer creates a temp/deployment-beans.xml which contains all
the beans defined in *-beans.xml file's from /deploy directory.
|
native |
Contains the native library to read/write from dahdi channels. As of now the native library is only for linux OS .
|
ss7 |
The ss7 directory contains the configuration file ss7-beans.xml for configuring the channels. One needs to configure the Channel and MTP beans and copy this file to /deploy to enable the SS7.
|
The Media Server uses a number of XML configuration files that control various aspects of the server.
The following example illustrates a truncated directory structure of the mms-standalone-<version>
server files:
[user@localhost <MMS_HOME>]$ tree |-- bin | |-- init_redhat.sh | |-- run.bat | |-- run.jar | `-- run.sh |-- conf | |-- bootstrap-beans.xml | `-- log4j.xml |-- deploy | |-- avprofile-beans.xml | |-- comp-beans.xml | |-- connection-beans.xml | |-- connection-states-beans.xml | |-- controllers | | `-- mgcp | | |-- mgcp-conf.xml | | `-- packages | | |-- au | | | |-- events.xml | | | |-- package | | | | `-- package.xml | | | `-- signals.xml | | `-- dtmf | | |-- events.xml | | |-- package | | | `-- package.xml | | `-- signals.xml | |-- endpoint | | |-- ann-beans.xml | | |-- cnf-beans.xml | | |-- ivr-beans.xml | | |-- mgw-beans.xml | | `-- packetrelay-beans.xml | |-- rtp-beans.xml | `-- server-beans.xml |-- lib | |-- activation-1.1.jar | |-- cmu_time_awb-1.2.2.jar | |-- cmu_us_kal-1.2.2.jar | |-- cmudict04-1.2.2.jar | |-- cmulex-1.2.2.jar | |-- cmutimelex-1.2.2.jar | |-- dtdparser121-1.2.1.jar | |-- en_us-1.2.2.jar | |-- freetts-1.2.2.jar | |-- jain-mgcp-ri-1.0.jar | |-- jain-sip-ri-1.2.X-20100813.024234-297.jar | |-- java-getopt-1.0.9.jar | |-- jaxb-api-2.1.9-brew.jar | |-- jboss-common-core-2.2.14.GA.jar | |-- jboss-dependency-2.0.6.GA.jar | |-- jboss-kernel-2.0.6.GA.jar | |-- jboss-logging-spi-2.1.0.GA.jar | |-- jboss-mdr-2.0.1.GA.jar | |-- jboss-reflect-2.0.2.GA.jar | |-- jbossxb-2.0.1.GA.jar | |-- jspeex-0.9.7.jar | |-- log4j-1.2.14.jar | |-- mbrola-1.2.2.jar | |-- mgcp-impl-2.0.0.GA.jar | |-- mms-controllers-mgcp-2.1.0.BETA1-SNAPSHOT.jar | |-- mms-controllers-rtsp-2.1.0.BETA1-SNAPSHOT.jar | |-- mms-impl-2.1.0.BETA1-SNAPSHOT.jar | |-- mms-spi-2.1.0.BETA1-SNAPSHOT.jar | |-- mms-standalone-2.1.0.BETA1-SNAPSHOT.jar | |-- mtp-1.0.0.BETA3.jar | |-- netty-3.2.0.BETA1.jar | |-- stream-1.0.0.BETA1.jar | |-- stun4j-1.0.MOBICENTS.jar | |-- tritonus_gsm-0.3.6.jar | |-- tritonus_share-0.3.6.jar | `-- xml-apis-2.9.1.jar |-- log | `-- server.log |-- mbrola | |-- mbrola | |-- mbrola.exe | |-- readme.txt | |-- us1 | | |-- license.txt | | |-- us1 | | |-- us1.txt | | `-- us1mrpa | |-- us2 | | |-- license.txt | | |-- us2 | | `-- us2.txt | `-- us3 | |-- license.txt | |-- us3 | `-- us3.txt |-- media | |-- 8kalaw.wav | |-- 8kulaw.wav | |-- gwn44m.wav | |-- gwn44s.wav | |-- sample_100kbit.mov | |-- sample_100kbit.mp4 | `-- sample_50kbit.3gp |-- native | `-- zap-native-linux.so |-- ss7 | `-- ss7-beans.xml `-- temp `-- deployment-beans.xml