The SIP Scenario Pack adds support for the Session Initiation Protocol to the OpenCloud Scenario Simulator.

Topics

Configuring the SIP Scenario Pack

configure the scenario pack

Running the Scenario Pack examples

install and run the examples included with the Scenario Pack

Documentation for the OpenCloud Scenario Simulator and other Scenario Packs, including links to changelogs and downloads, can be found on the Scenario Simulator product page.

Configuration

Below are properties for configuring the SIP Scenario Pack.

SIP Protocol Adaptor properties

Name Type Default Description

Transports

String

"UDP,TCP"

A comma-separated list containing supported SIP transports (one or more of UDP, TCP). The SIP Protocol Adaptor will open listen sockets for these transports. The first transport on the list will be used in the "transport" field of Via header in outgoing request when set as AUTO in a scenario.

Port

Integer

5060

Port that will be used for unencrypted SIP transports (UDP, TCP).

SecurePort

Integer

5061

Port that will be used for encrypted SIP transports (TLS). CAUTION: In current version of SIP Scenario Pack TLS is not supported.

ViaSentByAddress

String

null

Specifies an address (IP address or hostname) that will be used in the "address" field of Via header in outgoing request when set as AUTO in a scenario. By default this property is null, and the SIP Protocol Adaptor will use the local IP address of the endpoint.

AckRetransmitTimer

Long

32000

Specifies the duration (ms) after which a processed ACK will be removed from the internal cache, which affects the ACK/200 OK response retransmit behaviour. For the client, the SIP Protocol Adaptor will retransmit an ACK (if cached) on each matching final response retransmission to INVITE. For the server, it will retransmit an 200 OK response until it receives (caches for filtering out future retransmissions) a matching ACK.

Rel1xxRetransmitTimer

Long

32000

Specifies the duration (ms) of the 1xx (provisional) reliable responses retransmit timer. The SIP Protocol Adaptor will retransmit an 1xx reliable response until it receives a matching PRACK request or the associated timer expires.

ServerTransactionTimeout

Long

32000

The duration (ms) for which the SIP Protocol Adaptor will do automatic expiration any pending (which remain in state Trying/Proceeding) server transactions.

CcmWorkaroundEnabled

Boolean

false

The workaround for Cisco Call Manager, which may not have unique branch IDs. Use from-tag as an additional field in the transaction ID, to make it unique.

SIP stack properties

Name Type Default Description

StackName

String

"OCSIP"

Sets a user friendly name to identify the underlying SIP Stack implementation to the property value i.e. "alice". The stack name should contain no spaces.

OutboundProxy

String

null

Sets the outbound proxy of the SIP Stack. The format for this string is "ipaddress:port/transport" i.e. 129.1.22.333:5060/UDP.

Automatic100TryingSupport

Boolean

false

If enabled, the SIP Stack will automatically generate 100 Trying responses for INVITEs.

ErrorResponsesAckSuppression

Boolean

false

If enabled, the SIP Stack will suppress, and not pass up to the SIP Protocol Adaptor, incoming ACKs to error (3xx-6xx) responses to INVITEs. CAUTION: If enabled, ACKs to error responses should not be defined in scenarios.

MaxContentLength

Integer

131072

The maximum length (bytes) of SIP messages.

WorkerPoolSize

Integer

4

Number of worker threads the SIP Stack will use to process incoming messages. If zero, the SIP Protocol Adaptor will receive and process messages in the same I/O thread. Otherwise, the pool will be used so that incoming messages can be processed concurrently.

WorkerQueueSize

Integer

50

Queue size for the worker thread pool. If the queue fills then the SIP Stack will drop packets (UDP) or temporarily suspend reads (TCP).

TcpIoThreads

Integer

1

Number of threads for handling TCP I/O. TCP connections will be divided between the I/O threads.

TcpListenBacklog

Integer

0

Size of listen backlog queue for TCP server sockets. Increase to allow the server to accept more concurrent connection requests. A value less than or equal to 0 means use the Java platform’s default.

AllowLoopbackSend

Boolean

false

Allow the SIP Stack to send SIP messages to itself. Disabled by default.

RFC 3263 properties

Name Type Default Description

Rfc3263FailoverEnabled

Boolean

false

Specifies whether to use RFC 3263 failover. By default this is disabled, to match existing behaviour. If enabled, the SIP Stack 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.

Rfc3263FailoverTimer

Long

10000

Specifies the duration (ms) of the failover timer. If RFC 3263 failover is enabled and this timer expires before any responses were received, the SIP Stack 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.

Rfc3263BlacklistTimer

Long

300000

The duration (ms) for which a server will be blacklisted after a failure is detected. This avoids the SIP Stack 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 Retry-After duration in a 503 response, that value will be used instead.

Examples

The SIP scenario pack is bundled with example configuration and scenario files.

The examples may be found in the <scenario_simulator>/sip-examples directory.

The basic SIP examples are stand-alone scenarios using the Scenario Simulator only. The SIP Rhino examples show SIP integrating with the Rhino TAS.

Scenario Simulator Command Script File

Scenario Simulator command script files be can be found in <scenario_simulator>/sip-examples/config/*.commands.

There are scripts for multiple SIP endpoints setup used for sip-examples. These files contain scenario simulator commands. Usage of a commands script file is recommended but not required as it is possible to run all the required commands manually from the simulator prompt.

Below is the content of the setup-alice.commands script file:

set-endpoint-address alice alice
create-local-endpoint alice sip -propsfile sip-examples/config/setup-alice.properties
bind-role alice alice

set-endpoint-address bob bob.opencloud.co.nz:5260
bind-role bob bob

set-endpoint-address proxy1 proxy1.opencloud.co.nz:5560
bind-role proxy1 proxy1

The first set-endpoint-address command sets the address of "alice" to alice host name. It is assumed that there exits "alice" entry in /etc/hosts, substituting appropriate IP address.

The second set-endpoint-address commands sets the address of "bob" to bob.opencloud.co.nz:5260.

The last set-endpoint-address commands sets the address of "proxy1" to proxy1.opencloud.co.nz:5560.

Commands bind-role bind respectively the alice endpoint address to scenario role alice, bob endpoint address to scenario role bob, and proxy1 endpoint address to scenario role proxy1.

Basic Examples

Prerequisites

1

Add the following entries to /etc/hosts, substituting appropriate IP addresses for each simulator if they run on a remote server.

In this example all simulators are running on the local host.

127.0.0.1 alice alice.opencloud.co.nz
127.0.0.1 bob bob.opencloud.co.nz
127.0.0.1 proxy1 proxy1.opencloud.co.nz
127.0.0.1 proxy2 proxy2.opencloud.co.nz
127.0.0.1 registrar registrar.opencloud.co.nz
127.0.0.1 subscriber subscriber.opencloud.co.nz
127.0.0.1 notifier notifier.opencloud.co.nz

2

Start separate scenario simulators for each endpoint as needed for the examples below.

The examples assume the working directory is the simulator base directory --- the parent directory of the one containing this file.

./scenario-simulator.sh -l simulator-alice.log -f sip-examples/config/setup-alice.commands
./scenario-simulator.sh -l simulator-bob.log -f sip-examples/config/setup-bob.commands
./scenario-simulator.sh -l simulator-proxy1.log -f sip-examples/config/setup-proxy1.commands
./scenario-simulator.sh -l simulator-proxy2.log -f sip-examples/config/setup-proxy2.commands
./scenario-simulator.sh -l simulator-registrar.log -f sip-examples/config/setup-registrar.commands
./scenario-simulator.sh -l simulator-subscriber.log -f sip-examples/config/setup-subscriber.commands
./scenario-simulator.sh -l simulator-notifier.log -f sip-examples/config/setup-notifier.commands
Examples
Example 1. register.scen

  • Basic SIP registration (from s24.1 in RFC 3261)

  • Requires bob and registrar endpoints

  • Load scenario on both endpoints: load-scenario sip-examples/scenarios/register.scen

  • Run session from "bob" endpoint: run-session register

Example 2. 401-unsuccessful-regiser.scen

  • Basic SIP unsuccessful registration

  • Requires bob and registrar endpoints

  • Load scenario on both endpoints: load-scenario sip-examples/scenarios/401-unsuccessful-register.scen

  • Run session from "bob" endpoint: run-session 401-unsuccessful-register

Example 3. 404-reason.scen

  • SIP 404 Not Found error session

  • Requires alice and proxy1 endpoints

  • Load scenario on both endpoints: load-scenario sip-examples/scenarios/404-reason.scen

  • Run session from "alice" endpoint: run-session 404-reason

Example 4. no-answer.scen

  • SIP call attempt ended with no answer from bob

  • Requires alice, bob, proxy1 and proxy2 endpoints

  • Load scenario on all endpoints: load-scenario sip-examples/scenarios/no-answer.scen

  • Run session from "alice" endpoint: run-session no-answer

Example 5. normal-session.scen

  • Basic SIP call via two proxies (from s24.2 in RFC 3261)

  • Requires alice, bob, proxy1 and proxy2 endpoints

  • Load scenario on all endpoints: load-scenario sip-examples/scenarios/normal-session.scen

  • Run command from "alice" endpoint: run-session normal-session

Example 6. normal-session-bob-hangsup.scen

  • Similar to normal-session.scen but bob hangs up

  • Requires alice, bob, proxy1 and proxy2 endpoints

  • Load scenario on all endpoints: load-scenario sip-examples/scenarios/normal-session-bob-hangsup.scen

  • Run command from "alice" endpoint: run-session normal-session-bob-hangsup

Example 7. normal-session-prack.scen

  • Call flow via two proxies with provisional ack

  • Requires alice, bob, proxy1 and proxy2 endpoints

  • Load scenario on all endpoints: load-scenario sip-examples/scenarios/normal-session-prack.scen

  • Run command from "alice" endpoint: run-session normal-session-prack

Example 8. instant-messaging.scen

  • Basic SIP instant messaging flow

  • Requires alice, bob, proxy1 endpoints

  • Load scenario on all endpoints: load-scenario sip-examples/scenarios/instant-messaging.scen

  • Run command from "alice" endpoint: run-session instant-messaging

Example 9. refer.scen

  • basic SIP refer flow

  • requires alice and bob endpoints

  • load scenario on all endpoints: load-scenario sip-examples/scenarios/refer.scen

  • run command from "alice" endpoint: run-session refer

Example 10. subscription.scen

  • basic subscriber-notify SIP flow

  • requires subscriber and notifier endpoints

  • load scenario on both endpoints: load-scenario sip-examples/scenarios/subscription.scen

  • run session from "subscriber" endpoint: run-session subscription

SIP Rhino examples

The Scenario Pack contains some examples of SIP scenarios integrating with Rhino. The examples include:

  • Registering a SIP endpoint with a Rhino proxy server

  • An Instant-Messaging scenario that uses a Rhino SDK as the proxy server

  • A Normal-Call scenario that uses a Rhino SDK as the proxy server (proxy1).

Prerequisites
Important

In this example, the localhost is 192.168.0.28

Depending on how your host resolves localhost, you may need to change all references to localhost in the rhino-sip-examples/config/normal-session/setup* files and in the scenario files to your external IP address{info}

1

Esnure the Rhino SDK server and Scenario Simulator are both installed locally

2

Add/edit the following entries to /etc/hosts on the local host, using external IP addresses

192.168.0.28	alice alice.opencloud.co.nz
192.168.0.28	bob bob.opencloud.co.nz
192.168.2.28	proxy2 proxy2.opencloud.co.nz

3

Remove the entry for the loopback address in /etc/hosts (if you have it configured)

4

Start Rhino

5

Deploy the SIP-connectivity pack examples
Configure and running the examples

1

Register endpoint Bob with Rhino

  • start one scenario-simulator session with the command:

./scenario-simulator.sh -l bob.log -f rhino-sip-examples/config/register/setup-bob.commands -e 'load-scenario rhino-sip-examples/scenarios/rhino-connectivity-register-bob.scen'

  • run-session rhino-connectivity-register-bob

2

Run the Instant-Messaging example scenario:

  • start two scenario-simulator sessions with the commands:

./scenario-simulator.sh -l bob.log -f rhino-sip-examples/config/instant-messaging/setup-bob.commands -e 'load-scenario rhino-sip-examples/scenarios/rhino-connectivity-instant-messaging.scen'

./scenario-simulator.sh -l alice.log -f rhino-sip-examples/config/instant-messaging/setup-alice.commands -e 'load-scenario rhino-sip-examples/scenarios/rhino-connectivity-instant-messaging.scen'

  • run-session rhino-connectivity-instant-messaging (from alice endpoint)

3

Run the Normal-Session example scenario:

  • start three scenario-simulator sessions with the commands:

./scenario-simulator.sh -l bob.log -f rhino-sip-examples/config/normal-session/setup-bob.commands -e 'load-scenario rhino-sip-examples/scenarios/rhino-connectivity-normal-session.scen'

./scenario-simulator.sh -l proxy2.log -f rhino-sip-examples/config/normal-session/setup-proxy2.commands -e 'load-scenario rhino-sip-examples/scenarios/rhino-connectivity-normal-session.scen'

./scenario-simulator.sh -l alice.log -f rhino-sip-examples/config/normal-session/setup-alice.commands -e 'load-scenario rhino-sip-examples/scenarios/rhino-connectivity-normal-session.scen'

  • run-session rhino-connectivity-normal-session (from alice endpoint)