This document details basic procedures for system administrators installing, configuring, and managing Rhino SIP Servlet.
Topics
Other documentation for the Rhino SIP Servlet including the changelog and links to downloads, can be found on the Rhino SIP Servlet product page.
About Rhino SIP Servlet
Rhino SIP Servlet lets users deploy SIP Servlet applications alongside SLEE applications in the same Rhino instance.
It works using a SLEE Resource Adaptor (RA) and supporting libraries, which together provide a SIP Servlet 1.1 container environment inside the Rhino’s JAIN SLEE container. SIP Servlet applications can then be deployed into Rhino, without being aware they are running on a SLEE.
 |
Rhino SIP Servlet adds SIP Servlet 1.1 (JSR289) support to the OpenCloud Rhino JAIN SLEE platform. |
Installing and configuring Rhino SIP Servlet
Installing Rhino SIP Servlet means installing the Rhino SIP Servlet RA and its supporting libraries, and configuring the RA with suitable settings for its environment, such as network addresses, ports and so on. Once installed, Rhino SIP Servlet can be managed using its command-line console (sipservlet-console) or Ant tasks.
 |
This guide explains the procedures for installing and managing Rhino SIP Servlet. |
Installing Rhino SIP Servlet
To install the Rhino SIP servlet:
1 |
Check the system requirements:
|
||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
2 |
Extract the Rhino SIP Servlet package:
|
||||||||||||||||||||||
3 |
Create a SIP Servlet RA entity:
At this point, the SIP Servlet RA entity |
| |
The next sections describe how to configure Rhino SIP Servlet and deploy applications. |
Rhino SIP Servlet Management Interfaces
Below are brief introductions to Rhino SIP Servlet’s command-line, Ant, and MBean management interfaces.
(Sections further in this document explain in more detail how they are used for particular tasks.)
Command-line console
The sipservlet-console command is an extension to Rhino’s rhino-console. When you run sipservlet-console, all Rhino management commands are available, plus several SIP Servlet-specific commands. The help command shows the available command categories, including SIP Servlet. For help on a particular category or command, help <category> or help <command>.
| |
For more detail on the SIP Servlet commands, please see the SIP Servlet Console Reference. |
Setting CLIENT_HOME
The sipservlet-console script uses the CLIENT_HOME environment variable to locate the Rhino client directory and the rhino-console command. If Rhino SIP Servlet was extracted in the Rhino base directory as recommended, it’s not necessary to set CLIENT_HOME. Otherwise, you must set CLIENT_HOME in the shell to point to the correct location; for example:
$ export CLIENT_HOME=/home/user/rhino/client $ ./sipservlet-console
Ant tasks
Rhino SIP Servlet provides a set of Ant tasks for configuring the SIP Servlet RA and deploying SIP Servlet applications. The complete set of available tasks is described in the Ant.
Below are instructions for:
Enabling SIP Servlet tasks in your Ant build file
To make use of these tasks, an Ant build file must import Rhino SIP Servlet’s common.xml build file, and also declare a namespace prefix for these tasks using their antlib URI, antlib:com.opencloud.sipservlet.ant. For example:
<project name="my-project" xmlns:sipservlet="antlib:com.opencloud.sipservlet.ant">
<import file="${user.home}/rhino/sipservlet/common.xml"/>
<target name="deploy-servlet">
<sipservlet:connect raentity="ss"/>
<sipservlet:install srcfile="${jars}/my-servlet.sar"/>
<sipservlet:activate appname="my-servlet"/>
</target>
...
</project>Here the namespace prefix sipservlet is used, so the tasks are invoked as <sipservlet:connect>, <sipservlet:install>, and so on. The prefix was declared by the xmlns:sipservlet attribute in the root element. The prefix can be anything, as long as it doesn’t conflict with other namespace prefixes declared in the build file.
| |
The examples throughout this guide use the sipservlet prefix. |
Connecting to an RA entity
The first SIP Servlet task to run in an Ant build must be the
It’s also possible to have connections to multiple SIP Servlet RA entities in the same build. Here, the script connects to entities "foo" and "bar", and subsequent tasks can select a connection using the optional connectionrefid attribute:
<sipservlet:connect raentity="foo" id="ra1"/>
<sipservlet:connect raentity="bar" id="ra2"/>
...
<sipservlet:install connectionrefid="ra1" srcfile="${jars}/my-servlet.sar"/>
<sipservlet:install connectionrefid="ra2" srcfile="${jars}/my-servlet.sar"/>Setting Ant properties for installed applications
The
ServiceID in deployment scripts. This is useful because the script may not know these values in advance.
To set these properties when installing, use the optional prefix attribute on the
<sipservlet:install srcfile="myservlet.sar" prefix="myservlet"/>If installation is successful, the following project properties are automatically set:
| Property Name | Description |
|---|---|
prefix.app.name |
The deployed servlet application name. |
prefix.service.name |
deployed service’s |
prefix.service.vendor |
deployed service’s |
prefix.service.version |
deployed service’s |
Now a script can easily install and activate a servlet application, without knowing the ServiceID or application name in advance:
<sipservlet:install srcfile="myservlet.sar" prefix="myservlet"/>
<!-- successful install sets myservlet.app.name property. -->
<sipservlet:activate appname="${myservlet.app.name}"/>Resolving previously installed applications
Sometimes the method above will not be suitable because it relies on the
<sipservlet:resolve url="file:/path/to/myservlet.sar" prefix="myservlet"/>
<sipservlet:deactivate appname="${myservlet.app.name}"/>MBeans
All SIP Servlet management operations are accessible via JMX MBeans, so custom applications may also be used to manage Rhino SIP Servlet. The MBeans are registered with Rhino’s MBean server.
| |
The Javadoc for the Rhino SIP Servlet MBeans is available at docs/api/sipservlet-management/index.html. |
Configuring the SIP Servlet Resource Adaptor
The SIP Servlet Resource Adaptor (RA) gets its configuration from several sources.
Like most SLEE RAs, it uses configuration properties — configured values that the SLEE passes to an RA entity when it is created, and when its configuration is updated (for example, by way of rhino-console’s updateRAEntityConfigProperties command).
| |
Configuration Properties describes the available configuration properties. |
The SIP Servlet RA also uses several profile tables for storing configuration settings that are not easily represented using standard configuration properties. These profile tables must be created before the SIP Servlet RA entity is created. The bundled deployment script deploy.xml does this automatically.
| |
|
Active reconfiguration
All configuration property updates or management operations may be invoked on an active SIP Servlet RA entity. For some properties, however, updates may not apply immediately. If a SIP Servlet RA entity cannot apply a configuration change immediately, it will raise a SLEE alarm saying that the RA entity must be restarted for the changes to take effect. These alarms will appear in Rhino’s logs, and can be viewed in REM or rhino-console (listactivealarms).
If a configuration update fails for any reason, the SIP Servlet RA entity will raise an alarm, and try to continue with its last successful configuration.
Configuration Properties
These configuration properties may be specified when creating or updating an RA entity (createRAEntity and updateRAEntityConfigProperties management commands).
| Name | Type | Default Value | Reconfigurable while active? | Description |
|---|---|---|---|---|
config-profile |
String |
None, a value must be supplied on RA entity creation. |
✅ |
The ProfileID of the Configuration Profile that will be used to configure this RA entity. The string must be in the form "table-name/profile-name". |
WorkerPoolSize |
Integer |
4 |
❌ |
Number of worker threads the SIP Servlet RA will use to process incoming messages. If zero, the RA will process messages in the receiving I/O thread. Otherwise, messages will be handed off to the pool so they can be processed concurrently. |
WorkerQueueSize |
Integer |
500 |
❌ |
Queue size for the worker thread pool. If the queue fills, then the RA will drop packets (UDP) or temporarily suspend socket reads (TCP). |
TCPIOThreads |
Integer |
1 |
❌ |
Number of threads for handling TCP I/O. TCP connections will be divided between the I/O threads. |
AllowLoopbackSend |
Boolean |
false |
❌ |
Controls whether the RA may send SIP requests to its own addresses. Disabled by default to prevent accidental loops. |
Automatic100TryingSupport |
Boolean |
true |
✅ |
If enabled, the RA will automatically generate 100 Trying responses for INVITEs. |
OffsetPorts |
Boolean |
false |
❌ |
Required if running multiple cluster nodes on the same host. If true, the RA will automatically add an offset to each SIP network interface port, so that each RA instance gets a different port number. See |
PortOffset |
Integer |
0 |
❌ |
Required when running multiple cluster nodes on the same host. If |
fiber-pool.core-pool-size |
Integer |
2 |
✅ |
The RA’s fiber pool is a thread pool used for ordering execution of tasks within the SIP Servlet implementation. The core pool size is the minimum size of this thread pool. |
fiber-pool.max-pool-size |
Integer |
8 |
✅ |
The maximum number of threads that may be used by the fiber pool. |
fiber-pool.queue-size |
Integer |
500 |
✅ |
The maximum size of the fiber pool’s input queue. |
RFC3263:failover_enabled |
Boolean |
false |
❌ |
Specifies whether to use RFC 3263 Failover & Load Balancing. By default this is disabled, to match existing behaviour. If enabled, the RA uses RFC 3263 DNS procedures to find possible servers and automatically fails over to backup servers where available. If multiple servers are found in DNS, they are sorted and tried according to their SRV priority and weight as per RFC 2782. If disabled, the DNS procedures are still used to find server addresses, but only the first address is used. |
RFC3263:failover_timer |
Long |
10000 |
❌ |
Specifies the duration of the failover timer in milliseconds. If RFC 3263 failover is enabled and this timer expires before any responses were received, the RA treats this as a transport error and tries sending the request to the next available server. This timer should be set to a value smaller than the default Timer B and Timer F timers (32s) so that failures can be detected promptly. A value of zero or less disables this timer. |
RFC3263:blacklist_timer |
Long |
300000 |
❌ |
The duration in milliseconds for which a server will be blacklisted after a failure is detected. This avoids the RA trying to use the server immediately after a failure when it is most likely just going to fail again. After this time has passed the failed server may be tried again on subsequent client transactions. If a server specifies a |
SSL/TLS Properties
These properties are only used if a network interface is configured to use the TLS transport.
| Name | Type | Default Value | Reconfigurable while active? | Description |
|---|---|---|---|---|
Keystore |
String |
${rhino.dir.base}/
sipservlet-data/
sipservlet.keystore
|
❌ |
The name of a keystore file used to store private key material. |
KeystoreType |
String |
jks |
❌ |
The type of keystore implementation. |
KeystorePassword |
String |
Empty string (no password). |
❌ |
Password to unlock the keystore. |
Truststore |
String |
${rhino.dir.base}/
sipservlet-data/
sipservlet.keystore
|
❌ |
The name of a truststore file containing trusted CA certificates. May be same as |
TruststoreType |
String |
jks |
❌ |
|
TruststorePassword |
String |
Empty string |
❌ |
Password to unlock the truststore. |
CRLURL |
String |
None. |
❌ |
The location of a certificate revocation list. |
CRLRefreshTimeout |
Integer |
86400 |
❌ |
The certificate revocation list refresh timeout, in seconds. |
CRLLoadFailureRetryTimeout |
Integer |
900 |
❌ |
The certificate revocation list load failure timeout, in seconds. |
CRLNoCRLLoadFailure RetryTimeout |
Integer |
60 |
❌ |
The certificate revocation list load failure retry timeout, in seconds. |
ClientAuthentication |
String |
NEED |
❌ |
Indicate whether clients need to be authenticated against certificates in the truststore, must be one of
|
EnabledCipherSuites |
String |
|
❌ |
Comma-separated list of cipher suites to enable on all TLS sockets. If empty, the JVM’s default cipher suites will be used. See Java SE 6 cipher suites. |
SLEE Profile tables
Rhino SIP Servlet uses several profile tables for storing its configuration. Below are the default tables, which the bundled deployment script deploy.xml automatically creates when deploying the RA:
| Profile Spec Name | Default Table Name | Description |
|---|---|---|
|
SIP Servlet Config Profile |
config |
The config-profile configuration property refers to this profile. These attributes in the profile specify the names of the other profile tables used by the RA entity:
|
|
SIP Servlet Network Interface Profile |
interfaces |
Stores SIP network interface definitions. |
|
SIP Servlet Network Route Profile |
routes |
Stores routing rules that determine the outgoing network interface for requests. |
|
SIP Servlet Application Name Ref Profile |
application-names |
Stores the mappings of servlet application names to SLEE ServiceIDs. |
|
SIP Servlet Default Application Router Profile |
darconfig |
Stores Default Application Router configurations. |
| |
When creating a SIP Servlet RA entity, these profile tables must exist, but they may be empty. The exception is the configuration profile referred to by the config-profile configuration property: this profile must exist before creating the RA entity. It tells the RA where to find the other tables. The bundled deploy.xml script calls the macro create-rhino-sipservlet-instance, which creates the configuration profile config/<ra-entity>-config by default, using the profile table names above. |
Typically it will not be necessary to manipulate these tables directly; the defaults should be suitable in most cases. Rhino SIP Servlet’s management operations will update these profile tables as needed.
| |
Multiple SIP Servlet RA entities can share the same profile tables; it’s not necessary to create new profile tables to support additional RA entities. The implementation ensures that RA entities don’t overwrite each other’s settings. |
RFC 3263 Failover & Load Balancing
RFC 3263 — Locating SIP Servers specifies how SIP clients use DNS procedures to resolve a SIP URI into the address, port and transport protocol of the next server to contact. In addition, these DNS procedures can result in multiple addresses that clients can try sequentially if earlier addresses failed.
The SIP Servlet RA now supports RFC 3263 to provide failover and load balancing of outgoing requests. Previously the SIP Servlet RA used RFC 3263 only for determining the first address to contact; it did not automatically try backup addresses if the first address failed. Now the SIP Servlet RA has been updated to automatically failover to backup addresses as well, with no intervention required from the application.
Introduction to the RFC 3263 process
When a SIP client sends a request, it must select either the first Route header’s URI, if present, or the Request-URI. This URI determines where the request is sent to (the next-hop address). This URI might only contain a domain name, such as sip:bob@example.com. RFC 3263 DNS procedures are required to convert the URI into the address, port and transport protocol of an actual SIP server (or servers).
At a high level there are three parts to the RFC 3263 DNS process. Some of these may be skipped depending on what information is already given in the URI, such as transport, IP address or port numbers. Here is a simplified description of the process that applies to any SIP client using RFC 3263.
-
Determine the transport protocol. If not already specified in the URI, the client will do a DNS NAPTR lookup on the domain. This may return some NAPTR records which specify in order of preference the transport protocols that shall be used. The NAPTR records will contain SRV addresses for each supported transport protocol.
-
Next, determine the port. This can be found by looking up the SRV address in the NAPTR record. Or, if there were no NAPTR records, the SIP client will try the default SRV addresses for its preferred transport protocols, e.g. "_sip._tcp.example.com". The SRV query may return one or more SRV records. Each record contains the hostname and port of a SIP server. Multiple SRV records are sorted according to their priority and weight, and ordered randomly as per RFC 2782. This means that the results will be ordered slightly differently every time, providing a form of load balancing.
-
Finally the hostnames provided in SRV records must be looked up to obtain their IP addresses. Sometimes this information is already included in the SRV response. If there were no SRV records the SIP client will default to looking up the IP address of the hostname in the URI.
At the end of this process the SIP client has a list of (address, port, transport) tuples to try. If the list is empty then the request cannot be routed and will fail. Otherwise, the client picks the first address in the list and starts a client transaction. The next backup address will be tried if the transaction fails for any of these reasons:
-
the server responds with 503 (Service Unavailable)
-
the transaction times out
-
the transaction fails with a transport error
When such a failure occurs, the client selects the next address and tries again with a new client transaction. If all addresses failed then the client must fail the request.
SIP Servlet RA usage of RFC 3263
The SIP Servlet RA closely follows the RFC 3263 procedures but with some adaptations described below.
Use of client transactions
RFC 3263 states that a new client transaction is used for each backup address. The SIP Servlet RA does this, but the client transactions are hidden from the application. The application just sends a single SipServletRequest on a SipSession, as usual. If a failure occurs and there are backup addresses available, the RA automatically creates a new client transaction and sends the request to the backup address. The RA takes care of routing the successful responses up to the application’s SipSession.
Each new client transaction created for contacting backup servers will have a new Via branch ID (as per the RFC), but these are derived from the original branch ID with a different suffix for each new transaction. For example if the original branch was "z9hG4bK776asdhds", any subsequent transactions will have branches "z9hG4bK776asdhds%1", "z9hG4bK776asdhds%2" so on. In this way the branches for each transaction are still unique in the RA and the network, but can be correlated when looking at logs or packet captures. The application will only see the original branch ID in responses.
The first final response to be received will end the transaction and no more backup addresses will be tried. If all of the available addresses failed, the application will see the last error response received from a server (a 503 or 408 response), or the RA will generate a 503 response and pass it up to the application.
Failover timer
Failover to a backup server is triggered by transaction timeouts, transport errors or 503 responses. If a server has failed completely, the resulting transport error (such as ICMP Port Unreachable) may not be directly visible to the RA, especially when using UDP. Or there may be no ICMP rejects at all in the event of a network partition. This means failover will not occur until the transaction timeout (Timers B or F in RFC 3261) occurs, which will usually be 32 seconds!
For many applications it is desirable to try and detect failures a bit faster than this. The SIP Servlet RA defines an additional failover timer, which can expire before the default transaction timeout to trigger a failover faster. The default value of this timer is 10 seconds.
The failover timer is only started when there are multiple addresses to try. If there is just a single address, the normal transaction timeout behaviour applies. The timer is stopped as soon as any response (including 100 Trying) is received, as this indicates that the next-hop server is functioning. If this timer expires and no responses were received, the RA moves on to the next address.
Server blacklisting and recovery
By itself, DNS does not tell you if a server is available. When using the DNS process above, the same set of servers will always be returned, regardless of whether they are currently available or not. To avoid contacting servers that are likely to be down, the SIP Servlet RA maintains a "blacklist".
Whenever a server failure is detected, either by timeout, transport error or 503 response, the RA adds the failed address to a blacklist so that the address is not tried again for some period of time.
This avoids the RA needlessly contacting servers that are most likely going to be down. By default, servers are blacklisted for 5 minutes. After that time the RA will try using the address again.
Servers that respond with a 503 response and a Retry-After header will be blacklisted for the duration specified in the header.
Configuring the SIP Servlet RA for RFC 3263
See the RFC3263 configuration properties in Configuration Properties.
Network Configuration
When creating a Rhino SIP Servlet RA entity, you must also configure how it will connect to the network.
Rhino SIP Servlet’s network configuration consists of:
-
network interfaces — define the IP addresses, ports and transports that the RA entity will use for sending and receiving SIP traffic
-
network routes — specify which network interface to use for outgoing requests, when certain criteria are met.
Each RA entity must have at least one network interface. Routes are required if there is more than one network interface. Alarms are raised when attempting to activate an RA entity that has no network interfaces, or multiple interfaces and no routes.
Rhino SIP Servlet supports multihomed hosts as specified in JSR289 §14.2. Typically only one network interface is required, but multihoming can be useful in some situations. For example, Rhino SIP Servlet could proxy between clients on a public network, and some application servers on a hidden, private network.
Network Interfaces
You can use these procedures to manage network interfaces with Rhino SIP Servlet:
Configuring Network Interfaces
You configure network interfaces in Rhino SIP Servlet by setting these properties, when creating or updating an interface.
| Name | Type | Default Value | Reconfigurable while active? | Description |
|---|---|---|---|---|
IPAddress |
String |
None, a value must be specified. |
❌ |
The IP address (or hostname) of the network interface. Must match a local network interface on the host. The special value |
Port |
Integer |
5060 |
❌ |
The port that will be used for unencrypted SIP transports (UDP, TCP). |
SecurePort |
Integer |
5061 |
❌ |
The port that will be used for encrypted SIP transports (TLS). |
Transports |
String |
TCP,UDP |
❌ |
Comma-separated list of transports that the network interface supports. |
VirtualAddresses |
String |
None |
❌ |
Comma-separated list of virtual IPs or hostnames that are considered to be local, such as virtual addresses provided by an external load balancer. Incoming requests that are routed to a local address will be processed by the SIP Servlet RA before forwarding. Addresses may also include a port number, e.g. |
ViaSentByAddress |
String |
None |
❌ |
The hostname that will be used as the sent-by address in Via headers of requests sent on this interface. |
UseVirtualAddressInURIs |
Boolean |
True |
❌ |
If true and |
 |
Changes to the network interface configuration of an active SIP Servlet RA entity will not be applied until the RA entity is restarted. |
Viewing Network Interfaces
Use sipservlet-console to view the currently configured set of network interfaces.
| To… | Use this console command: |
|---|---|
|
List all network interfaces |
listnetworkinterfaces <ra-entity> |
|
List all enabled network interfaces |
listenablednetworkinterfaces <ra-entity> |
|
Display properties of a network interface |
dumpnetworkinterface <ra-entity> <interface-name> |
|
List all supported network interface properties |
listsupportedproperties <ra-entity> |
Creating Network Interfaces
Below are the sipservlet-console and Ant for creating network interfaces.
| |
Network interfaces must be created with a unique name and an IPAddress property. Other optional properties may also be specified. The network interface will not be used until it is enabled on an RA entity. |
Console
Syntax |
createnetworkinterface <ra-entity> <interface-name> (<property> <value>)* |
|---|---|
Example |
To create a network interface on a specific port ( createnetworkinterface ss private IPAddress auto Port 5099 |
Ant
Syntax |
<sipservlet:createnetworkinterface name="..."> <sipservlet:property name="..." value="..."/> </sipservlet:createnetworkinterface> |
|---|---|
Example |
To create a network interface on a specific port ( <sipservlet:createnetworkinterface name="private"> <sipservlet:property name="IPAddress" value="auto"/> <sipservlet:property name="Port" value="5099"/> </sipservlet:createnetworkinterface> |
Updating Network Interfaces
Below are the sipservlet-console and Ant commands for updating network interfaces.
| |
The properties of a network interface can be updated by specifying the interface name and the new property values. In sipservlet-console or Ant, setting a property value to the literal string null removes the property from the network interface, so the property reverts to its default value. |
Console
Syntax |
updatenetworkinterface <ra-entity> <interface-name> (<property> <value>)* |
|---|---|
Example |
To update a network interface’s address and port: updatenetworkinterface ss public IPAddress 192.168.99.4 Port 5600 |
Ant
Syntax |
<sipservlet:updatenetworkinterface name="..."> <sipservlet:property name="..." value="..."/> </sipservlet:updatenetworkinterface> |
|---|---|
Example |
To update a network interface’s address and port: <sipservlet:updatenetworkinterface name="public"> <sipservlet:property name="IPAddress" value="192.168.99.4"/> <sipservlet:property name="Port" value="5600"/> </sipservlet:updatenetworkinterface> |
Enabling Network Interfaces
Below are the sipservlet-console and Ant commands for enabling network interfaces.
| |
Enabling a network interface assigns it to a particular RA entity. When the RA entity is activated, it will begin accepting SIP traffic on the interface. |
Disabling Network Interfaces
Below are the sipservlet-console and Ant commands for disabling network interfaces.
| |
Disabling a network interface means it will no longer be used by the RA entity. |
Removing Network Interfaces
Below are the sipservlet-console and Ant commands for removing network interfaces.
| |
Network interfaces may be removed as long as they are not enabled on an RA entity. |
Network Routes
Rhino SIP Servlet uses its network routes to determine the appropriate outbound network interface for outgoing requests.
| |
Network routes are only required when the SIP Servlet RA entity has two or more network interfaces enabled. |
| |
Changes to the network route configuration of an active SIP Servlet RA entity will not be applied until the RA entity is restarted. |
Determining the outbound interface
The SIP Servlet RA uses a routing table, which is an ordered sequence of network routes. Users modify the RA’s routing table by adding, removing, or moving network routes.
When the RA needs to send a SIP request on the network, it looks at the request’s next-hop address. This is the hostname or IP address in the first Route header, if present, or the address of the Request-URI. Note that this occurs before RFC3263 name resolution procedures are applied.
Each configured network route has a rule, and a network interface to use if the rule matches the next-hop address. The RA iterates over the table, and the first route to match the next-hop address is selected. If no rules match, the default route will be used.
| |
A servlet can explicitly select an outbound network interface using SipSession.setOutboundInterface() or SipSession.setOutboundInterface(). This setting overrides the RA’s routing table. |
Routing rules
Network routes are created by specifying a rule, and a network interface to use if the rule is matched. The available rules are:
-
ip — matches if the next-hop address (or its resolved address) is in the given IP address range. For example,
ip 10.0.0.0/8matches addresses10.0.0.0-10.0.0.255. -
subdomain — matches if the hostname is inside a given domain. For example,
subdomain opencloud.commatchesproxy.opencloud.com. -
regex — performs a regularexpression match on the next-hop address. For example,
regex media.*\.abc\.commatchesmediaserver.abc.com.
Default route
The default route is a special rule that is always evaluated last. It specifies a network interface that requests will be sent on if no other routes matched.
| |
When two or more network interfaces are enabled, it is good practice to configure the default route — to prevent requests falling through and being rejected because no other routes matched. |
Relationship to host routing table
Rhino SIP Servlet will not modify the host’s routing table. It assumes that the operator will update the host routing table as necessary. For example, if the SIP Servlet RA has a rule that says all requests to 192.168.0.0/24 should use the interface "private", then the operator must ensure that the corresponding physical network interface can actually send to those addresses — that the interface is directly attached to the 192.168.0.0/24 network, or has a route to that network.
Displaying the Routing Table
Use sipservlet-console to display the routing table.
Syntax |
listnetworkroutes <ra-entity> |
|---|---|
Example |
> listnetworkroutes ss 0: ip 192.168.0.0/16 -> private 1: domain services.foo.com -> apps |
Specifying the Default Route
Below are the sipservlet-console and Ant commands for specifying the default route.
| |
The default route will always be checked last, if all other routes did not match. |
Removing the Default Route
Below are the sipservlet-console and Ant commands for removing the default route.
Adding a Route
Below are the sipservlet-console and Ant commands for adding a route.
| |
New routes are added after any existing routes, unless a position is specified, starting from zero. |
Removing a Route
Below are the sipservlet-console and Ant commands for removing a route.
Moving a Route
Below are the sipservlet-console and Ant commands for moving a route.
| |
|
Updating a Route
Below are the sipservlet-console and Ant commands for updating a route.
Updating the Default Route
Below are the sipservlet-console and Ant commands for updating the default route.
Application Deployment
Regular SLEE services must be installed using deployable units, or DUs. These are JAR files containing the service deployment descriptor, Service Building Block (SBB) component JAR files, and supporting libraries.
Each installed DU is identified by a unique URL, which can later be used to uninstall the DU, removing the service and its components from the SLEE.
When a SIP Servlet application’s SAR file is deployed, Rhino SIP Servlet automatically generates a container service for the SIP Servlet application, and packages it inside a DU, along with the original SAR file. The resulting DU is then installed in the SLEE.
The new SIP Servlet application DU is installed with the following default properties:
-
The DU’s URL is the
file:URL of the original SAR file. -
The servlet application name is that defined in the SAR’s
sip.xmldeployment descriptor, or@SipApplicationannotation. -
The ServiceID of the container service is:
name=SIP Servlet Application: app-name,vendor=OpenCloud,version=1.0
These properties may all be overridden at deployment time — see Installing a SIP Servlet Application.
Once deployed, the new service can be managed with the normal Rhino SLEE management commands, such as activateservice, deactivateservice, and so on. Rhino SIP Servlet provides some additional commands that let services be addressed by their servlet application names instead of their SLEE ServiceIDs.
| |
This section assumes that the application is packaged as a SAR file. |
See the following procedures for deploying and undeploying SIP Servlet applications in Rhino SIP Servlet:
Installing a SIP Servlet Application
Below are the sipservlet-console and Ant commands for installing a SIP Servlet application.
| |
Installing a SIP Servlet application automatically generates a container service and deploys it in Rhino. |
Console
Syntax |
install-ss <ra-entity> <sar-file> [-appname <name>] [-linkname <name>] [-service <service-id>] |
|---|---|
Examples |
To override the default ServiceID: install-ss ss myservlet.sar -service name=myservlet,vendor=abc,version=1 By default, Rhino SIP Servlet creates an application name reference mapping the servlet application’s name to its install-ss ss myservlet.sar -appname newname |
Ant
Syntax |
<sipservlet:install srcfile="..." appname="..." linkname="..." url="..."> <sipservlet:service name="..." vendor="..." version="..."/> </sipservlet:install>
|
||
|---|---|---|---|
Examples |
To override the default ServiceID: <sipservlet:install srcfile="myservlet.sar"> <sipservlet:service name="myservlet" vendor="abc" version="1"/> </sipservlet:install> To override the default application name: <sipservlet:install srcfile="myservlet.sar" appname="newname"/> |
Uninstalling a SIP Servlet Application
Below are the sipservlet-console and Ant commands for uninstalling a SIP Servlet application.
| |
You uninstall a SIP Servlet application the same way as a regular SLEE service, by uninstalling the service’s deployable unit. This can be done with the standard Rhino uninstall command. |
Console
Syntax |
uninstall <sar-url> |
|---|---|
Example |
To uninstall a SAR DU: uninstall file:/path/to/myservlet.sar |
Ant
Syntax |
<slee-management> <uninstall url="..."/> </slee-management> or, to also remove the servlet application’s application name reference: <sipservlet:uninstall url="..." removeappname="true/false"/> |
|---|---|
Example |
To uninstall a SAR DU: <slee-management> <uninstall url="file:/path/to/myservlet.sar"/> </slee-management> or <sipservlet:uninstall url="file:/path/to/myservlet.sar" removeappname="true"/> |
Activating a SIP Servlet Application
Below are the sipservlet-console and Ant commands for activating a SIP Servlet application
| |
After installation, a SIP Servlet application must be activated before it will begin processing SIP messages. You activate an application by activating its SLEE service, with Rhino’s activateservice command. |
Console
Syntax |
activateservice <service-id> |
|---|---|
Example |
activateservice name=myservlet,vendor=abc,version=1 |
Ant
Syntax |
<activateservice> <component name="..." vendor="..." version="..."/> </activateservice> or, using the servlet application name instead of the <sipservlet:activate appname="..."/> |
|---|---|
Example |
<slee-management>
<activateservice>
<component name="${myservlet.service.name}" vendor="${myservlet.service.vendor}" version="${myservlet.service.version}"/>
</activateservice>
</slee-management>
or <sipservlet:activate appname="${myservlet.app.name}"/>
|
Deactivating a SIP Servlet Application
Below are the sipservlet-console and Ant for deactivating a SIP Servlet application
| |
You deactivate a SIP Servlet application by deactivating its SLEE service, with Rhino’s deactivateservice command. |
Console
Syntax |
deactivateservice <service-id> |
|---|---|
Example |
deactivateservice name=myservlet,vendor=abc,version=1 |
Ant
Syntax |
<deactivateservice> <component name="..." vendor="..." version="..."/> </deactivateservice> or, using the servlet application name instead of the <sipservlet:deactivate appname="..."/> |
|---|---|
Example |
<slee-management>
<deactivateservice>
<component name="${myservlet.service.name}" vendor="${myservlet.service.vendor}" version="${myservlet.service.version}"/>
</deactivateservice>
</slee-management>
or <sipservlet:deactivate appname="${myservlet.app.name}"/>
|
Application Name References
As explained in Application Naming, installing SIP Servlet application SAR files in Rhino SIP Servlet automatically creates application name references. These are mappings between the application’s name and its corresponding SLEE ServiceID.
It should not be necessary to manually update application name references, unless you’re deploying a hybrid application, or there is a naming conflict.
Use the following procedures to manually update application name references:
Viewing Application Name References
Below are the sipservlet-console commands for viewing application name references.
Syntax |
To list all application name references: listapplicationnamerefs <ra-entity> To dump an application name reference, showing its dumpapplicationnameref <ra-entity> <name> |
|---|
Creating an Application Name Reference
Below are the sipservlet-console and Ant commands for creating an application name reference.
| |
Creating an application name reference maps a servlet application name to a SLEE ServiceID. |
Console
Syntax |
createapplicationnameref <ra-entity> <name> <service-id> |
|---|---|
Example |
createapplicationnameref ss my-app name=My-Service,vendor=abc,version=1 |
Ant
Syntax |
<sipservlet:createapplicationnameref name="..."> <sipservlet:service name="..." vendor="..." version="..."/> </sipservlet:createapplicationnameref> |
|---|---|
Example |
<sipservlet:createapplicationnameref name="my-app"> <sipservlet:service name="My-Service" vendor="abc" version="1"/> </sipservlet:createapplicationnameref> |
Removing an Application Name Reference
Below are the sipservlet-console and Ant commands for removing an application name reference.
Replacing an Application Name Reference
Below are the sipservlet-console and Ant commands for replacing an application name reference.
| |
An existing application name reference can have its ServiceID replaced with a new ServiceID. |
Console
Syntax |
replaceapplicationnameref <ra-entity> <name> <service-id> |
|---|---|
Example |
replaceapplicationnameref ss my-app name=New-Service,vendor=abc,version=2 |
Ant
Syntax |
<sipservlet:replaceapplicationnameref name="..."> <sipservlet:service name="..." vendor="..." version="..."/> </sipservlet:replaceapplicationnameref> |
|---|---|
Example |
<sipservlet:replaceapplicationnameref name="my-app"> <sipservlet:service name="New-Service" vendor="abc" version="2"/> </sipservlet:replaceapplicationnameref> |
Application Router Configuration
The Application Router selects which SIP Servlet applications process a call.
| |
A valid application router configuration must be installed before the SIP Servlet RA can process SIP messages. |
See the following sections about managing application routers:
Default Application Router
All SIP Servlet 1.1 containers support the Default Application Router (DAR). You configure it using a properties file. The DAR may only have a single configuration active at a time.
You configure the Rhino SIP Servlet’s DAR at run time, using the following procedures:
Viewing the DAR Configuration
Below is the sipservlet-console command for viewing the DAR configuration.
Syntax |
get-dar-config <ra-entity> |
|---|
Installing a DAR Configuration
Below are the sipservlet-console and Ant commands for installing a DAR configuration.
| |
A DAR configuration can be installed from a text file, or by specifying the DAR configuration inline in the Ant task. Installing a new DAR configuration automatically replaces the RA entities' previous DAR configuration, if any. The change takes effect immediately. |
Console
Syntax |
install-dar-config <ra-entity> <config file> |
|---|---|
Example |
install-dar-config ss /path/to/dar.properties |
Ant
Syntax |
<sipservlet:installdarconfig file="..."/> or including the DAR configuration inline: <sipservlet:installdarconfig> <!-- Insert DAR rules here... ---> </sipservlet:installdarconfig> |
|---|---|
Example |
<sipservlet:installdarconfig file="/path/to/dar.properties"/> or inline: <sipservlet:installdarconfig>
INVITE: ("my-app", "DAR:P-Served-User", "ORIGINATING", "", "NO_ROUTE", "0"), ...
</sipservlet:installdarconfig>
|
Removing the DAR Configuration
Below are the sipservlet-console and Ant commands for removing the DAR configuration.
| |
Removing the DAR configuration means that no applications will be selected, so Rhino SIP Servlet will reject new SIP requests. Removing the configuration takes effect immediately. |
Custom Application Routers
A custom application router can be installed following the procedures in SIP Servlet 1.1 §15.4.2.
-
The application router must be packaged as a Jar file using the Java SE Service Loader conventions.
This means the application router jar file must contain a
META-INF/services/javax.servlet.sip.ar.spi.SipApplicationRouterProviderfile, which contains the name of SipApplicationRouterProvider concrete class to load.Alternatively, the concrete class can be specified by setting the
javax.servlet.sip.ar.spi.SipApplicationRouterProvidersystem property. -
The application router jar file must be on the class path of the SIP Servlet RA.
The simplest way is to add it to the Rhino instance’s
CLASSPATH.Alternatively, it could be added to the SIP Servlet RA’s deployable unit jar file (
du/sipservlet-ra-1.x.y.z.du.jar).
| |
When a SIP Servlet RA entity is created, it will first try the javax.servlet.sip.ar.spi.SipApplicationRouterProvider system property, then the Service Loader mechanism to locate an application router implementation. If no application router is found, the RA entity will use the Default Application Router. |
Appendix A. SIP Servlet Console Reference
This appendix describes all commands available in sipservlet-console.
Deployment commands
install-ss
Description |
Installs a SIP Servlet Application sar file. Optionally overrides the default application name or ServiceID. |
|---|---|
Syntax |
install-ss <ra-entity> <sar-file> [-appname <name>] [-service <service-id>] |
createapplicationnameref
Description |
Creates an application name reference bound to a SLEE service. |
|---|---|
Syntax |
createapplicationnameref <ra-entity> <name> <service-id> |
dumpapplicationnameref
Description |
Displays the value of an application name reference. |
|---|---|
Syntax |
dumpapplicationnameref <ra-entity> <name> |
listapplicationnamerefs
Description |
Lists all application name references. |
|---|---|
Syntax |
listapplicationnamerefs <ra-entity> |
Network interface commands
createnetworkinterface
Description |
Adds a new network interface definition to the SIP Servlet RA entity. May include a list of property names and values for the interface; see Configuring Network Interfaces. |
|---|---|
Syntax |
createnetworkinterface <ra-entity> <interface-name> (<property-name> <property-value>)* |
disablenetworkinterface
Description |
Disables a network interface (so the SIP Servlet RA entity stops using it). |
|---|---|
Syntax |
disablenetworkinterface <ra-entity> <interface-name> |
dumpnetworkinterface
Description |
Displays the current configuration of a network interface. |
|---|---|
Syntax |
dumpnetworkinterface <ra-entity> <interface-name> |
enablenetworkinterface
Description |
Enables a network interface, which assigns it to the RA entity. When the RA entity is then activated, it will begin accepting SIP traffic on that interface. |
|---|---|
Syntax |
enablenetworkinterface <ra-entity> <interface-name> |
listenablednetworkinterfaces
Description |
Lists all enabled network interfaces on a SIP Servlet RA entity. |
|---|---|
Syntax |
listenablednetworkinterfaces <ra-entity> |
listnetworkinterfaces
Description |
Lists all network interfaces. |
|---|---|
Syntax |
listnetworkinterfaces <ra-entity> |
listsupportedproperties
Description |
Lists all supported network interface properties. |
|---|---|
Syntax |
listsupportedproperties <ra-entity> |
removenetworkinterface
Description |
Removes a network interface definition from the SIP Servlet RA entity. |
|---|---|
Syntax |
removenetworkinterface <ra-entity> <interface-name> |
updatenetworkinterface
Description |
Updates a new network interface definition with the given properties. A property value of "null" removes that property from the network interface, reverting it to its default value. |
|---|---|
Syntax |
updatenetworkinterface <ra-entity> <interface-name> (<property-name> <property-value>)* |
Network route commands
adddefaultnetworkroute
Description |
Adds a default route rule to a SIP Servlet RA entity. |
|---|---|
Syntax |
adddefaultnetworkroute <ra-entity> <interface-name> |
addnetworkroute
Description |
Add a new network route rule to a SIP Servlet RA entity. Rules are matched against the target address of outgoing requests (the host-part of the top Route header or Request-URI). These rule types are supported:
|
|---|---|
Syntax |
addnetworkroute <ra-entity> <rule> <interface-name> [position] |
listnetworkroutes
Description |
Displays all network routes on the RA entity. |
|---|---|
Syntax |
listnetworkroutes <ra-entity> |
movenetworkroute
Description |
Moves a network route from one position to another. |
|---|---|
Syntax |
movenetworkroute <ra-entity> <old-position> <new-position> |
removedefaultnetworkroute
Description |
Removes the default route from a SIP Servlet RA entity. |
|---|---|
Syntax |
removedefaultnetworkroute <ra-entity> |
removenetworkroute
Description |
Removes a route from a SIP Servlet RA entity. |
|---|---|
Syntax |
removenetworkroute <ra-entity> <position> |
Appendix B. SIP Servlet Ant Task Reference
This appendix describes all commands available in sipservlet-console.
How to add the SIP Servlet Ant tasks to your project
-
Import Rhino SIP Servlet’s
common.xml:<import file="/path/to/rhino/sipservlet/common.xml"/>
-
Declare a namespace for the SIP Servlet tasks:
<project name="servlet-app" xmlns:sipservlet="antlib:com.opencloud.sipservlet.ant">
-
Use the Ant tasks in your targets:
<sipservlet:connect raentity="ss"/> <sipservlet:install srcfile="${jars}/servlet-app.sar"/>
Parameters common to all Ant tasks
All Rhino SIP Servlet Ant tasks support these optional attributes:
| Attribute | Description | Required |
|---|---|---|
connectionrefid |
The id of a previous |
No, defaults to last successful connection. |
failonerror |
Default failure behaviour for this task. If set to "false" or "no", the build will continue when this task attempts a redundant action, such as installing an application that already exists. Unrecoverable errors will still fail the build. |
No, default is "false". |
Ant tasks
Below are descriptions and parameters for SIP Servlet Ant tasks.
connect
What it does |
Establishes a connection to a SIP Servlet RA entity. Connections are saved in memory for use by subsequent SIP Servlet tasks in the same Ant build (same JVM instance). Therefore this task must be executed before any other SIP Servlet tasks. Subsequent SIP Servlet tasks in the build use the last successful connection, unless a different connection is requested using the The |
|||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Ant parameters |
|
install
What it does |
Installs SIP Application SAR archives. Packages a SAR archive for deployment on Rhino and deploys it as a service. |
|||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Ant parameters |
The location of the SAR file to read, and the URL to associate with it when passing it to Rhino is determined as follows:
|
|||||||||||||||
Parameters available as nested elements |
|
uninstall
What it does |
Uninstalls SIP Application SAR archives. |
|||||||||
|---|---|---|---|---|---|---|---|---|---|---|
Ant parameters |
|
resolve
What it does |
Looks up the application name and |
|||||||||
|---|---|---|---|---|---|---|---|---|---|---|
Ant parameters |
|
|||||||||
Example |
<sipservlet:resolve url="file:${jars}/proxy.sar" prefix="proxy"/>
<!-- now use ${proxy.*} properties in script -->
<sipservlet:deactivate appname="${proxy.app.name}"/>
|
activate
What it does |
Activates a SIP Servlet service using its servlet application name instead of its |
||||||
|---|---|---|---|---|---|---|---|
Ant parameters |
|
deactivate
What it does |
Deactivates a SIP Servlet service using its servlet application name instead of its |
|||||||||
|---|---|---|---|---|---|---|---|---|---|---|
Ant parameters |
|
deploy (macro)
What it does |
|||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Ant parameters |
|
||||||||||||
Parameters available as nested elements |
|
undeploy (macro)
What it does |
Macro that deactivates and uninstalls a SIP Servlet application, and removes its application names, in one step. Calls the deactivate and deactivate tasks. |
||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Ant parameters |
|
settracerlevel (macro)
What it does |
|||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Ant parameters |
|
createapplicationnameref
What it does |
Create a application name reference for a SIP Servlet RA entity. |
||||||
|---|---|---|---|---|---|---|---|
Ant parameters |
|
||||||
Parameters specified as nested elements |
|
removeapplicationnameref
What it does |
Remove an application name reference from a SIP Servlet RA entity. |
||||||
|---|---|---|---|---|---|---|---|
Ant parameters |
|
createnetworkinterface
What it does |
Create a network interface definition for a SIP Servlet RA entity. |
||||||
|---|---|---|---|---|---|---|---|
Ant parameters |
|
||||||
Parameters specified as nested elements |
|
removenetworkinterface
What it does |
Removes a network interface definition from a SIP Servlet RA entity. |
||||||
|---|---|---|---|---|---|---|---|
Ant parameters |
|
enablenetworkinterface
What it does |
Enables a network interface on a SIP Servlet RA entity. |
||||||
|---|---|---|---|---|---|---|---|
Ant parameters |
|
disablenetworkinterface
What it does |
Disables a network interface on a SIP Servlet RA entity. |
||||||
|---|---|---|---|---|---|---|---|
Ant parameters |
|
updatenetworkinterface
What it does |
Updates a network interface definition for a SIP Servlet RA entity. |
||||||
|---|---|---|---|---|---|---|---|
Ant parameters |
|
||||||
Parameters specified as nested elements |
|
adddefaultnetworkroute
What it does |
Adds a default network route to a SIP Servlet RA entity. An RA entity may only have a single default route. |
||||||
|---|---|---|---|---|---|---|---|
Ant parameters |
|
addnetworkroute
What it does |
Adds a network route to a SIP Servlet RA entity. |
||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Ant parameters |
|
removedefaultnetworkroute
What it does |
Removes the default network route from a SIP Servlet RA entity. |
|---|---|
Ant parameters |
This task does not have any parameters. |
removenetworkroute
What it does |
Removes a network route from a SIP Servlet RA entity. |
||||||
|---|---|---|---|---|---|---|---|
Ant parameters |
|
updatedefaultnetworkroute
What it does |
Updates an existing default network route in a SIP Servlet RA entity. |
||||||
|---|---|---|---|---|---|---|---|
Ant parameters |
|
updatenetworkroute
What it does |
Updates an existing network route in a SIP Servlet RA entity. |
|||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Ant parameters |
|
installdarconfig
What it does |
Installs a Default Application Router (DAR) configuration in a SIP Servlet RA entity. |
||||||
|---|---|---|---|---|---|---|---|
Ant parameters |
|
||||||
Inline DAR configuration |
If the |
||||||
Examples |
<sipservlet:installdarconfig file="${resources}/prepay.dar.properties"/>
<sipservlet:installdarconfig>
INVITE: ("prepay", "DAR:From", "ORIGINATING", "", "NO_ROUTE", "0")
SUBSCRIBE: ("presence", "DAR:From", "ORIGINATING", "", "NO_ROUTE", "1")
</sipservlet:installdarconfig>}
|
uninstalldarconfig
What it does |
Uninstalls the Default Application Router (DAR) configuration from a SIP Servlet RA entity. |
|||
|---|---|---|---|---|
Ant parameters |
|
Service element
What it does |
SIP Servlet tasks that require a |
||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Ant parameters |
|
Property element
What it does |
This element specifies a property to pass when updating a network interface definition. See Configuring Network Interfaces. |
|||||||||
|---|---|---|---|---|---|---|---|---|---|---|
Ant parameters |
|