This documentation relates to last stable version of Cipango.
visit the last unstable documentation home.
Configuring and Running Cipango
Running Cipango
Cipango may be started and stopped as follows:
- From the #Command Line
- As a #Unix daemon
Command Line
The most straightforward way to start Cipango is to go to your Cipango installation directory and type:
java -jar start.jar --ini=start-cipango.ini
To stop, simply use Ctrl-C in the same terminal. You may also start Cipango so that it listens on a local port for stop commands:
java -DSTOP.PORT=8079 -DSTOP.KEY=secret -jar start.jar --ini=start-cipango.ini
The server can then be stopped using a different terminal window on the same machine:
java -DSTOP.PORT=8079 -DSTOP.KEY=secret -jar start.jar --stop
If you omit the stop port or key, they are displayed on the standard output so that you may know their values.
Unix daemon
To start Cipango under *nix system,
- set in
${jetty.home}/etc/jetty.conf
(The line--ini=start-cipango.ini
--pre=etc/jetty-logging.xml
must be removed) - go to
${jetty.home
} and type:./bin/jetty.sh start
This script allows also the commands stop, run, restart, check and supervise.
shell commands
jetty.sh lookup for
/etc/default/jetty
$HOME/.jettyrc
If they exist, these files are read at script startup. It may perform any sequence of shell commands, like setting relevant environment variables
# Where Cipango is installed JETTY_HOME=/home/user/cipango JAVA_HOME=/usr/local/jdk1.6.0 # Set max heap sise to 512MB and initial size to 256MB JAVA_OPTIONS=="-Xmx512M -Xms256M -XX:+UseParNewGC -XX:+UseConcMarkSweepGC" # Override the default SIP host SIP_HOST=192.168.1.2 #Override the default SIP port SIP_PORT=5060 #Override the default HTTP port JETTY_PORT=8080 if [ ! -z "$SIP_PORT" ] then JAVA_OPTIONS="${JAVA_OPTIONS} -Dsip.port=${SIP_PORT}" fi if [ ! -z "$SIP_HOST" ] then JAVA_OPTIONS="${JAVA_OPTIONS} -Dsip.host=${SIP_HOST}" fi
Environnement properties
Property |
Description |
---|---|
JETTY_HOME |
Where Cipango is installed. If not set, the script will try go guess it by first looking at the invocation path for the script, and then by looking in standard locations as
|
JAVA_HOME |
Home of your Java installation |
JAVA |
Command to invoke Java. If not set, |
JAVA_OPTIONS |
Extra options to pass to the JVM |
JETTY_CONSOLE |
Where Jetty console output should go. Defaults to first writeable of
|
JETTY_PORT |
Override the default HTTP port for Cipango servers. If not set then the default value in the xml configuration file will be used. The java system property "jetty.port" will be set to this value for use in |
JETTY_RUN |
Where the jetty.pid file should be stored. It defaults to the first available of |
JETTY_PID |
The jetty PID file, defaults to |
JETTY_ARGS |
The default arguments to pass to Jetty. |
jetty.conf
It also search for jetty.conf
in
/etc/jetty.conf
${jetty.home}/etc/jetty.conf
This file will be used as this script's configuration.
Each line in the file may contain:
- A comment denoted by the pound (#) sign as first non-blank character.
- The path to a regular file, which will be passed to Cipango as a config.xml file.
- The path to a directory. Each *.xml file in the directory will be passed to Cipango as a config.xml file.
If more than one argument is passed to the script (jetty.sh start etc/cipango.xml
), jetty.conf is not read
Absolute path must be used if Cipango is not started from ${jetty.home}/bin
Configuring Cipango
Application Router
Default Application Router
The Default application Router (DAR) looks for its configuration file in the following order:
javax.servlet.sip.ar.dar.configuration
system property specifying the path to the configuration file- if not set the default value
${jetty.home}/etc/dar.properties
is used
If the configuration file is not found or is empty, the Default Application Router always selects the first deployed application in alphabetic order.
DAR configuration file
The DAR configuration file format is defined in SIP Servlets 1.1 specification in annex C.1.
# Default Application router configuration # Properties file in which the name of the property is the SIP method and the value is a simple comma separated stringified value for the SipApplicationRouterInfo object # Example: INVITE: ("OriginatingCallWaiting", "DAR:From", "ORIGINATING", " ", "NO_ROUTE", "0"), ("CallForwarding", "DAR:To", "TERMINATING", " ", "NO_ROUTE", "1")
In this example, the DAR is setup to invoke two applications on INVITE request, the first in the originating part and the second in the terminating half. The applications are identified by their names as defined in the application deployment descriptors. The subscriber identity returned in this case is the URI from the From and To header respectively for the two applications. The DAR does not return any route to the container and maintains the invocation state in the stateInfo as the index of the latest application in the list.
Routing Outgoing Requests
As defined in JSR289, the Application Router is invoked to route both incoming and outgoing requests. Since it may be useful not to use the Application Router on outgoing requests, it is possible to configure the Default Application Router to prevent it from processing outgoing requests.
To do so, you can set the System property org.cipango.dar.routeOutgoingRequests
to false, for instance:
java -Dorg.cipango.dar.routeOutgoingRequests=false -jar start.jar etc/cipango.xml
Alternatively, you can use the setRouteOutgoingRequests
on the Default Application Router in the cipango.xml
configuration file, as shown below:
<Set name="applicationRouter"> <New class="org.cipango.dar.DefaultApplicationRouter"> <Set name="configuration"><SystemProperty default="." name="jetty.home"/>/etc/dar.properties</Set> <Set name="routeOutgoingRequests">false</Set> </New> </Set>
Custom application router
To add a custom application router, drop the jar file containing your application router in the directory ${jetty.home}/lib/ext
.
To make Cipango load your custom application router, you can either:
- remove the default application library: delete the file
${jetty.home}/lib/ext/cipango-dar-VERSION.jar
- or use the system property
javax.servlet.sip.ar.spi.SipApplicationRouterProvider
to define the customSipApplicationRouterProvider
- or define the application router in
${jetty.home}/etc/cipango.xml
, for instance<Set name="applicationRouter"> <New class="com.acme.MyApplicationRouter"> </New> </Set>
JNDI
JNDI is not enabled by default in Cipango.
To add JNDI and SIP Servlet annotation support, Cipango should be started with cipango-plus.xml
configuration file:
java -jar start.jar --ini=start-cipango.ini etc/cipango-plus.xml
JNDI support is similar to Jetty's one. Documentation on how to bind objects in JNDI tree is available here
SIP Connectors
TLS
To add TLS support, Cipango should be started with cipango-tls.xml
configuration file:
java -jar start.jar --ini=start-cipango.ini etc/cipango-tls.xml
To manage the keys, see Jetty SSL plugin
System properties
In addition to system properties defined by Jetty, Cipango may use the following properties:
Property name |
default value |
description |
---|---|---|
SIP |
|
|
sip.host |
127.0.0.1 |
host on which SIP connector is listening |
sip.port |
5060 |
port on which SIP connector is listening |
sip.mtu |
65536 |
MTU (Maximum Transmission Unit) used to define if the request is sent on UDP or TCP. (See RFC 3261 §18.1.1) |
|
|
|
javax.servlet.sip.ar.dar.configuration |
file:///${jetty.home}/etc/dar.properties |
URI to the default application router configuration file. |
javax.servlet.sip.ar.spi.SipApplicationRouterProvider |
null |
Class name of the |
org.cipango.dar.routeOutgoingRequests |
true |
if set to |
|
|
|
snmp.host |
0.0.0.0 |
host on which SNMP connector is listening |
snmp.port |
161 |
port on which SNMP connector is listening |
snmp.trap.host |
localhost |
host on which SNMP traps are sent |
snmp.trap.port |
162 |
port on which SNMP traps are sent |
|
|
|
diameter.host |
0.0.0.0 |
host on which Diameter connector is listening |
diameter.port |
3868 |
port on which Diameter connector is listening |
For instance to set the SIP port to 5070, use:
java -Dsip.port=5070 -jar start.jar --ini=start-cipango.ini
Some properties like the port can be set in /etc/default/cipango. For more information, see Running Cipango