This document explains how to use the OpenCloud TCAP Simulator, which lets you test the unified CGIN resource adaptor without a full TCAP stack environment.

Topics

This document includes the following topics:

About the Simulated TCAP Stack

The unified CGIN resource adaptor includes a simulated Transaction Capabilities Application Part (TCAP) stack that can be used for testing with the need for a full TCAP stack environment.

The simulated TCAP stack supports both International Telecommunications Union (ITU) and American National Standards Institute (ANSI) TCAP.

Note
It’s a simulator …​

The simulator includes most of the behaviour of a real SS7 network, but it is not necessarily identical. For example, it may only communicate with other instances of the simulated TCAP stack.
Testing with the simulated stack is not a substitute for testing on a real network.

How does it work?

Each TCAP simulator instance (resource adaptor entity or Scenario Simulator) connects to other TCAP simulator instances using a subset of SUA over either SCTP or a proprietory TCP-based protocol.

The simulator is configured with one or more network addresses to connect to, plus an address to listen on. PC/SSN routing is configured automatically using standard SUA dynamic routing configuration.

A single pointcode/subsystem number pair may be routed to more than one simulator instance, allowing for operation within a Rhino cluster. The following diagram shows a simple 2-node Rhino cluster loaded with an ITU TCAP simulator resource adaptor entity connecting to the Scenario Simulator.

ITU TCAP
Figure 1. Simulator resource adaptor entity connected to Scenario Simulator

Configuring the Simulator

You configure the CGIN RA frontend for the Simulated TCAP stack by managing resource adaptor entity properties.

You can manage the CGIN RA configuration the same as you would any other resource adaptor entity configuration — for example, using rhino-console’s createraentity command.

Note The Simulated TCAP Stack is included with the CGIN Connectivity Pack. When you unpack the CGIN Connectivity archive, the Simulated TCAP stack will be in the cgin-unified-ra deployable unit, in the du directory.

Below are details of the following parameters you can set, and an example.

Properties for configuring the Simulator

Click for details of the following parameters.

Parameter Description Format Requirements/Options

stack=tcapsim

mandatory

tcapsim.listen-addresses

addresses to listen on

comma-separated list, in format <host>:<port>[:<nodeID>]

mandatory
may be empty

tcapsim.remote-addresses

remote addresses to connect to

comma-separated list, in format <host>:<port>[:<nodeID>]

mandatory
may be empty

tcapsim.sctp-stack

SCTP implementation to use

= tcp

3 options: tcp, sctp and auto

tcapsim.gt-table

global title translation table

= /path/to/gt/table.txt

mandatory
may be an empty file

tcapsim.max-dialogs

maximum simultaneously active dialogs

= integer

optional

local-sccp-address

local SCCP address

= formattedSccpAddress

mandatory

tcap-variant

TCAP variant

= ITU

2 options: ITU or ANSI

default-tcap-version

default TCAP version

= integer

2 options: 2000 (ITU and ANSI TCAP) or 1988 (ANSI TCAP only)

default-activity-timeout

default activity timeout in ms

= integer

optional

tcap-fibers.max-pool-size

maximum number of worker threads

= integer

optional
must be >= 1
takes effect on RA activation only

tcapsim.listen-addresses

This property is a comma-separated list of <host>:<port> values.

Optionally, a host:port value may be prefixed by <nodeID>,<nodeID>,…​ to have that address be applied on the given nodes only.

For example, the value:

{101}host1:1234,{102}host1:1235

causes node 101 to listen on host1:1234, and node 102 to listen on host1:1235.

To listen on all available network interfaces, use a <host> of 0.0.0.0

The <nodeID> parameter is only required if multiple Rhino nodes are running on a single host. When this parameter is specified, an RA entity will only create a listening socket on the specified host and port if the node that the entity is running on is equal to <nodeID>.

tcapsim.remote-addresses

This property is a comma-separated list of <host>:<port> values.

Optionally, a host:port value may be prefixed by <nodeID>,<nodeID>,…​ to have that address be applied on the given nodes only.

For example, the value:

{101}host1:1234,{102}host1:1235

causes node 101 to connect to host1:1234, and node 102 to connect to host1:1235.

It is unlikely that the <nodeID> parameter will be required as generally every node in a cluster should make connections to the same remote endpoints.

tcapsim.sctp-stack

This property controls the SCTP implementation used by the SUA stack. The options available are tcp, sctp and auto.

tcp is a proprietary SCTP-ish protocol running over TCP.

sctp is only available on JVMs that support SCTP and only where the underlying OS also supports SCTP.

auto attempts to automatically detect if the underlying JVM and OS support SCTP, and if they do, it will use it. If SCTP is not supported, the simulator will fall back to TCP.

tcapsim.gt-table

This parameter is the full path to the file containing the global title translation table.

The TCAP Simulator includes basic Global Title Translation support. Global titles can be mapped to a PC/SSN for routing according to the routing table. The format of the global title translation table is as follows:

# For all address types the first column contains the GlobalTitleIndicator.
#
# Then, for ITU-T, and ANSI when national=false, the format is:
#   1 C7 AddressDigits PC SSN NatureOfAddress
#   2 C7 AddressDigits PC SSN TranslationType
#   3 C7 AddressDigits PC SSN TranslationType NumberingPlan
#   4 C7 AddressDigits PC SSN TranslationType NumberingPlan NatureOfAddress
#
# And, for ANSI when national=true, the format is:
#   1 A7 AddressDigits PC SSN TranslationType NumberingPlan
#   2 A7 AddressDigits PC SSN TranslationType
#
# The J7 (Japanese) format is the same as for ITU-T, excepting that 'C7' is
# replaced with 'J7'.
#
# A match will only be returned if the GTI-specific parameters match and the
# leading digits of the address match the rule.  In the case of multiple
# matching rules the most specific address match will be returned.

#
# ITU-T Examples
#

# ITU-T SCCP address, gti=1, digits=123456*, na=1, pc=2, ssn=221
# 1 C7 123456 2 221 1

# ITU-T SCCP address, gti=1, digits=1234*, na=1, pc=2, ssn=221
# 1 C7 1234   2 211 1

# ITU-T SCCP address, gti=2, digits=98131*, tt=122, pc=1, ssn=232
# 2 C7 98131  1 232 122

# ITU-T SCCP address, gti=3, digits=78341*, pc=7183, ssn=6, tt=1, np=4
# 3 C7 78341  7183 6 1 4

# ITU-T SCCP address, gti=4, digits=81931239, pc=4, ssn=200, tt=89, np=1, na=1
# 4 C7 81931239 4 200 89 1 1

#
# ANSI Examples, with national=true
#

# ANSI SCCP address, gti=1, digits=73737*, tt=10, np=4, pc=2-123-42, ssn=6
# 1 A7 73737 2-123-42 6 10 4

# ANSI SCCP address, gti=2, digits=12345*, tt=42, pc=1-1-1, ssn=221
# 2 A7 12345 1-1-1 221 42

#
# J7 Examples
#

# Japanese SCCP address, gti=1, digits=123456*, na=1, pc=2, ssn=221
# 1 J7 123456 2 221 1

# Japanese SCCP address, gti=1, digits=1234*, na=1, pc=2, ssn=221
# 1 J7 1234   2 211 1

# Japanese SCCP address, gti=2, digits=98131*, tt=122, pc=1, ssn=232
# 2 J7 98131  1 232 122

# Japanese SCCP address, gti=3, digits=78341*, pc=7183, ssn=6, tt=1, np=4
# 3 J7 78341  7183 6 1 4

# Japanese SCCP address, gti=4, digits=81931239, pc=4, ssn=200, tt=89, np=1, na=1
# 4 J7 81931239 4 200 89 1 1

tcapsim.max-dialogs

The maximum number of dialogs that may be active simultaneously. This may be any positive 32-bit integer value. The default is 10000.

local-sccp-address

Provides a local calling party SCCP address to use for outgoing TC-BEGIN messages, if not explicitly provided by the SBB. The address should be formatted in the format that com.opencloud.slee.resources.cgin.SccpAddressParser expects. This parameter is mandatory.

This address is also the address used in dynamic routing configuration; it is the address this node advertises to another node when connecting to it.

Tip See SCCP Address Format in the CGIN Installation and Administration Guide.

tcap-variant

The TCAP variant to use: ITU or ANSI. The default is ITU.

default-tcap-version

The TCAP version to assume when this cannot be automatically determined. This may be the case for:

  • Inbound dialogs where the Dialogue Portion is absent, or there is no Protocol Version field in the Dialogue Portion. For example, MAP phase 1.

  • Outbound dialogs where a TCAP version has not been specified in the issueOpenRequest API call.

Valid options are:

  • ITU TCAP: 2000

  • ANSI TCAP: 2000 and 1988

When in 1988 mode, ANSI TCAP will:

  • Use Reject-in-Response to report transaction portion problems.

  • Format Reject components using the 1988-style formatting. i.e. ParamSet instead of ParamSequence

  • Dialog.sendUserAbort will send a Response without pending components instead of an Abort package.

The default is 2000.

default-activity-timeout

Configures the default timeout, in milliseconds, for tcapsim dialog activities. Each dialog has an activity timer associated with it. If no activity is seen on the dialog before the timer expires the dialog will be aborted and the associated SLEE activity ended. Sending or receiving messages on the dialog will reset this timer.

This is not to be confused with invoke timeouts, which apply to individual operations sent on a dialog.

tcap-fibers.max-pool-size

Configures the upper limit on tcapsim worker threads. This setting must be greater than or equal to 1, and changes to it will only take effect next time the RA is activated.

Sample configuration

For example, the diagram in About the Simulated TCAP Stack shows a configuration with the following properties:

Node 101 and Node 102:

stack=tcapsim
local-sccp-address="type=c7,ri=pcssn,pc=1,ssn=221"
tcapsim.gt-table=/home/user/rhino/rhino/cgin/gtt.txt
tcapsim.listen-addresses="{101}0.0.0.0:10221,{102}0.0.0.0:10231"
tcapsim.remote-addresses="127.0.0.1:10222"
tcapsim.max-dialogs=60000
tcap-variant=ITU
default-tcap-version=2000
default-activity-timeout=300

Scenario Simulator:

stack=tcapsim
local-sccp-address="type=c7,ri=pcssn,pc=2,ssn=222"
tcapsim.gt-table=/home/user/rhino/rhino/cgin/gtt.txt
tcapsim.listen-addresses="127.0.0.1:10222"
tcapsim.remote-addresses="127.0.0.1:10221,127.0.0.1:10231"
tcap-variant=ITU
default-tcap-version=2000

Running the Simulator

Create and start resource adaptor entities

To run the TCAP simulator:

1

Create and start all resource adaptor entities required to create the mesh.

2

Ensure that all simulators have completely created their connections before trying to use them.

Warning Otherwise, exceptions may be thrown by simulators that haven’t yet been able to complete all of their connections.

3

Use the simulated TCAP stack just as you would normally use the CGIN unified resource adaptor.

Tip No modifications to services are necessary.

Starting the simulated TCAP stack with other tools

To start the simulated TCAP stack, the TCAP simulator just needs the TCAP simulator resource adaptor entity parameters. You can use any tools that work to:

1

Create a properties file with the required simulated TCAP properties.

2

Pass this file to the create-local-endpoint command in the Scenario Simulator.
Tip

For more information, see the Scenario Simulator User Guide.

For example Appendix A. Full Command Listing documents the following command:

"create-local-endpoint": Creates (or re-creates) a local endpoint using the
        address of the given endpoint
    Usage: create-local-endpoint <endpoint-name> <protocol-adaptor-type>
        [-propsfile properties-file]
         -propsfile - Configuration properties for the endpoint
    Example: create-local-endpoint theSwitch cgin -propsfile
        config/cgin.properties