Using the Ulticom Signalware TCAP Stack

This document explains how to configure the OpenCloud CGIN Resource Adaptor to use the Signalware ITU TCAP stack implementation.

See the CGIN Compatibility Guide for details on the versions of Signalware that work with this version of the CGIN RA.

Topics

This document includes the following topics:

About the Signalware TCAP Stack Implementation describes and illustrates the architecture behind the Signalware ITU TCAP stack implementation.
Configuring the TCAP backends provides instructions, tables of options, and examples for installing and configuring TCAP backend processes for CGIN.
Configuring the CGIN RA frontend provides instructions for configuring CGIN resource adaptor entity properties that the Signalware TCAP stack supports.

About the Signalware TCAP Stack Implementation

The Signalware TCAP stack implementation for CGIN consists of two parts:

a Java "frontend" library, deployed on each Rhino node as part of the CGIN RA; and
a C++ "backend" executable, run within the Signalware platform environment, that is linked against the Signalware ITU TCAP library.

Frontend - backend processes

It works like this:

Each frontend establishes TCP/IP connections to all configured backends.
The Signalware platform receives incoming TCAP traffic from the network,
... and directs that traffic to the appropriate backend process.
The backend performs basic TCAP processing, using the Signalware ITU TCAP library,
... and passes the results to a frontend deployed in a Rhino node.
The frontend library then passes this data to the CGIN Unified RA.
The CGIN Unified RA performs protocol-specific decoding to produce SLEE events,
... and fires those events to Rhino.
In Rhino, SLEE services process those events,
... and send outgoing TCAP traffic to the CGIN Unified RA.
The CGIN Unified RA performs protocol-specific encoding,
... and passes TCAP data to the frontend.
The frontend passes that data to the appropriate backend process for the dialog.
The backend passes the TCAP data to the Signalware ITU TCAP library.
The Signalware ITU TCAP library then passes the resulting encoded data to the Signalware platform.
And the Signalware platform sends that data to the network.

Frontends and backends for each resource adaptor entity

For a single resource adaptor entity configured in Rhino, there will be one or more frontends (one per Rhino node), and one or more backends (as configured in the Signalware deployment).

All the backends associated with a particular resource adaptor entity have an identical configuration — multiple backends in this case are only needed for performance and redundancy reasons; they are otherwise equivalent.

Configuring the TCAP Backends

Prerequisites for backend installation

Before installing and configuring the backends, make sure that you have installed a licensed, supported Signalware platform installation with support for TCAP, appropriately configured with point codes and links.

To get, install, and configure the backend binaries for the TCAP stack:

1

The backend binaries are packaged as part of the CGIN Connectivity Pack, at signalware/<signalware_version>-<signalware_architecture>/<backend_version>/.

To install them, copy the contents of the directory matching your version to an installation location of your choice, on each CE of your Signalware installation.

2

To configure and start them, please see:

Starting the Backends
Backend Command-Line Options
Configuring for Failover and Recovery
Sample TCAP Configurations

Starting the Backends

The backend processes are simple processes that are configured entirely using command-line arguments.

The backend processes do not provide special logging or process-management functionality themselves — they expect that their parent process will manage restarting the backend if necessary, and will capture stdout/stderr to an appropriate logging mechanism. To help with logging, a start-backend.sh script allows logging of backend output to a file, or (through a pipe) to a separate process.

You can start the backends:

automatically, using Signalware’s process-management system (recommended)
manually, running start-backend.sh with command-line options.

Configuring Signalware to automatically start the backends

The recommended way to start the backends is to configure Signalware’s process-management system to start the backend processes. The benefits of this approach are:

Signalware will automatically restart processes that fail unexpectedly.
The lifecycle of the backends is coupled with the lifecycle of Signalware as a whole, so separate backend startup/shutdown procedures are not needed.
The state of individual backends can be managed using Signalware’s process-management MML commands.

To configure a backend in this way, execute the CREATE-PROCESS and START-PROCESS MML commands using the Signalware MML tools (such as swmml):

CREATE-PROCESS:NAME="logical_name",CE="ce_name",UID=numeric_uid,GID=numeric_gid,
EXEC="/path/to/backend/installation/start-backend.sh -logfile /path/to/logfile.txt
-node ss7_node_name -lssn numeric_local_ssn -port numeric_local_port -verbose";

START-PROCESS:NAME="logical_name",CE="ce_name";

This example has been line-wrapped for readability; each command should be executed as a single line. Note that:

logical_name is the logical process name that will be assigned to the process by Signalware. It must be unique per CE.
ce_name is the name of the Signalware CE (host) to start the process on.
numeric_uid is the numeric UID of the operating system user to run the process as.
numeric_gid is the numeric GID of the operating system group to run the process as.
The EXEC parameter controls the command line to execute — see Backend Command-Line Options.

Once configured, the CREATE-PROCESS command is persistent, and the backend will automatically be started whenever the Signalware instance is started.

In a multi-CE cluster, the CREATE-PROCESS MML commands may be executed on any CE. Signalware arranges for the commands to be propagated to the correct CE for execution.

For more on the MML commands, please see the Signalware CREATE-PROCESS and START-PROCESS manpages.

Manually starting the backends

Backends may be started manually (not using Signalware). This may be useful for manual testing, or when another tool provides process management.

In this case, start-backend.sh may be run directly, with appropriate arguments.

Ensure restart, environment, name

The process starting the backend should:

ensure that the backend is restarted on exit (where appropriate)
configure an appropriate environment (such as uid, gid) to execute as
pass an appropriate -ln logical_name on the backend command line, to provide a unique Signalware process name.

Backend Command-Line Options

Regardless of how you start them, you configure the TCAP backends using the following command-line options:

Option Argument Default Effect

Common options
❎ = required

-help

n/a

Displays a brief summary of supported options, then exits.

-version

n/a

Displays backend version information, then exits.

-verbose

n/a

Shows a summary of configured options, then continues with normal execution.

-ln

logical process name

❎ if not started using START-PROCESS

Sets the Signalware logical process name — must be unique within this CE.

-lssn

numeric SSN
❎

Sets the local SSN to accept traffic on.

-node

SS7 logical node name
❎

Sets the logical SS7 node to bind to, corresponding to a node configured using configureNodes.

-port

numeric TCP port
❎

Sets the local TCP port to accept Rhino connections on. Must be unique within this CE.

-trace

n/a

Enables logging of a brief summary of received/sent TCAP traffic to stderr.

-backup

backup process name

Enables recovery, and specifies a backend process that will act as the backup process for this process.

See Configuring for Failover and Recovery.

Options not usually needed in normal operation, but supported for tuning and debugging

-debug

n/a

Enables Signalware library debug logging.

-tcapdebug

hexadecimal debug mask

Enables Signalware TCAP stack debug logging.

-maxdialogs

numeric value

Sets maximum concurrent TCAP dialogs for this backend.

-maxisms

numeric value

Sets maximum concurrent TCAP ISMs for this backend.

-maxtimers

numeric value

Sets maximum concurrent TCAP timers for this backend.

-maxtblocks

numeric value

Sets maximum number of TCAP components per network message.

-debugflags

comma-separated flag list

Enables backend debug logging; use
-debugflags help for a list of supported flags.

-scostimeout

numeric value in seconds

(30 minutes)

Sets the lifetime of backup dialog data stored in SCOS.

Other options supported by start-backend.sh

-scripthelp

n/a

Shows a brief summary of extra options supported by the script and exits.

-type

backend type string

itutcap

no other values currently supported

Specifies the type of backend to use.

-variant

SS7 variant string

C7

Specifies the SS7 variant to use, either C7 or J7.

-binpath

path to backend install

the directory containing start-backend.sh

Specifies the base path to find binaries in.

-logfile

path to log file

Redirects all backend logging to append to the specified file.

See the table of substitutions.

At most one of -logfile or -logpipe may be specified. If neither is specified, stdout and stderr logging are not redirected.

-logpipe

command line followed by --

Redirects all backend logging using a pipe to the given command (shell escapes will be interpreted).

Arguments following -logpipe are passed to the pipe command, until -- is seen; arguments following -- are treated as normal script arguments.

See the table of substitutions.

At most one of -logfile or -logpipe may be specified. If neither is specified, stdout and stderr logging are not redirected.

-ulimit

arguments to the ulimit shell command

Changes resource limit parameters before executing the backend. For example, -ulimit -c unlimited will enable unlimited-size core dumps. See help ulimit.

Table of substitutions

The -logfile and -logpipe perform substitutions on their argument to produce a final filename or command line:

String Substituted by…

String	Substituted by…
%%	a literal single percent character (`%`).
%t	the backend type (set using `-type`).
%s	the local SSN (set using `-lssn`).
%v	the SS7 variant in use (set using `-variant`).
%p	the TCP port in use (set using `-port`).
%P	the PID of the backend process.

%%

a literal single percent character (%).

%t

the backend type
(set using -type).

%s

the local SSN
(set using -lssn).

%v

the SS7 variant in use
(set using -variant).

%p

the TCP port in use
(set using -port).

%P

the PID of the backend process.

Configuring for Failover and Recovery

The backends support failover and recovery from a backend or CE failure through the Signalware "backup process" mechanism.

A backend may specify a (single) backup process. If the original backend fails, for example due to CE failure, then the backup process will recover the dialogs the failed process was responsible for, and take over their processing.

Failure recovery can never be perfect — network messages currently being processed at the time of failure will be lost — so 100% of dialogs cannot always be recovered.

How to configure a backup process

To configure a backup process, use the -backup cename.processname syntax, specifying the CE name and logical process name of the backup process.

The backup process must be configured with the same SS7 variant, SS7 logical node, and local SSN as the primary process.

Normally, processes will be configured in pairs, with each member of a pair acting as backup for the other.

Sample TCAP Configurations

Sample MMLs for configuring backends

Below are three sample TCAP backend configurations.

MML	CREATE-PROCESS:NAME="backend_146_1",CE="turbine2",UID=101,GID=101, EXEC="/home/omni/backends/start-backend.sh -logfile /var/log/rhino/backend_146_1.%P.log -node rhino -lssn 146 -port 11146";
Configures a backend that:	is managed by the Signalware process-management system executes on CE `turbine2` with process name `backend_146_1, UID 101, GID 101` receives traffic for SS7 node `rhino` on SSN `146` listens for frontend connections on TCP port `11146` logs to a file named `/var/log/rhino/backend_146_1.<pid>.log`, with the appropriate backend PID substituted.

MML

CREATE-PROCESS:NAME="backend_146_1",CE="turbine2",UID=101,GID=101,
EXEC="/home/omni/backends/start-backend.sh -logfile /var/log/rhino/backend_146_1.%P.log -node rhino -lssn 146 -port 11146";

Configures a backend that:

is managed by the Signalware process-management system
executes on CE turbine2 with process name backend_146_1, UID 101, GID 101
receives traffic for SS7 node rhino on SSN 146
listens for frontend connections on TCP port 11146
logs to a file named /var/log/rhino/backend_146_1.<pid>.log, with the appropriate backend PID substituted.

MML

CREATE-PROCESS:NAME="backend_146_2",CE="turbine2",UID=101,GID=101,
EXEC="/home/omni/backends/start-backend.sh -logpipe /usr/local/bin/cronolog /var/log/rhino/backend_146_2.%%Y%%m%%d.log — -node rhino -lssn 146 -port 12146 -trace";

Configures a backend that:

is managed by the Signalware process management system
executes on CE turbine2 with process name backend_146_2, UID 101, GID 101
receives traffic for SS7 node rhino on SSN 146
listens for frontend connections on TCP port 12146
logs tracing of TCAP components sent and received
pipes log output to the command /usr/local/bin/cronolog /var/log/rhino/backend_146_2.%Y%m%d.log, providing log rollover to a series of date-based logs.

To include a literal % character in the arguments to cronolog, it must be specified as %% in the argument given to -logpipe.

The cronolog command line must be ended with --.

For more about cronolog, see cronolog.org.

MML	CREATE-PROCESS:NAME="backend_147",CE="turbine2",UID=101,GID=101, EXEC="/home/omni/backends/start-backend.sh -logfile /var/log/rhino/backend_147.log -node rhino -lssn 147 -port 11147 -backup turbine4.backend_147"; CREATE-PROCESS:NAME="backend_147",CE="turbine4",UID=101,GID=101, EXEC="/home/omni/backends/start-backend.sh -logfile /var/log/rhino/backend_147.log -node rhino -lssn 147 -port 11147 -backup turbine2.backend_147";
Configures a backend that:	execute on different CEs use the same TCP port and process name (acceptable, as they are on different CEs) specify each other as backups, to provide dialog recovery if one CE fails.

MML

CREATE-PROCESS:NAME="backend_147",CE="turbine2",UID=101,GID=101,
EXEC="/home/omni/backends/start-backend.sh -logfile /var/log/rhino/backend_147.log -node rhino -lssn 147 -port 11147 -backup turbine4.backend_147";
CREATE-PROCESS:NAME="backend_147",CE="turbine4",UID=101,GID=101,
EXEC="/home/omni/backends/start-backend.sh -logfile /var/log/rhino/backend_147.log -node rhino -lssn 147 -port 11147 -backup turbine2.backend_147";

Configures a backend that:

execute on different CEs
use the same TCP port and process name (acceptable, as they are on different CEs)
specify each other as backups, to provide dialog recovery if one CE fails.

Configuring the CGIN RA Frontend

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

Manage like any other resource adaptor entity

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.

The Signalware TCAP stack supports the following configuration properties:

Property
What it does

How to configure it

stack

Controls which TCAP stack the CGIN RA entity should use.

To use the Signalware TCAP stack, set stack=signalware.

Changes to this property will only take effect when the RA entity is next activated.

signalware.backends

Configures which backend processes to connect to.

Must be specified when the Signalware TCAP stack is used. The property is a comma-separated list of host:port values identifying the backend TCP ports to connect to. The host and port should correspond to the configured backend CE and -port values. Because the comma character has special meaning when entering configuration properties, the entire value should be quoted when more than one backend is configured.

For correct operation, all backends configured for a particular RA entity should be equivalent — they should be configured for the same SS7 variant, logical SS7 node, and local SSN.

signalware.base-weight

Specifies "full-rate" node weights per node.

Comma-separated list of items. One simple numeric value must be included — this is the weight used for nodes not otherwise specified. Optionally, additional {nodeID,..}weight values may be specified to provide different weights for different nodes. For example, the value 100,{101}50,{102,103}75 specifies a weight of 50 for node 101, a weight of 75 for nodes 102 and 103, and a default weight of 100 for all other nodes.

Each weight is a positive integer used to balance incoming load between nodes. The values have no particular unit other than relative to each other. A node will receive new dialogs in proportion to its weight; for example, two nodes with weights of 10 will receive about the same number of dialogs each, and a node with a weight of 20 will receive twice as many as a node with a weight of 10.

One approach is to treat them as percentages and assign 100 to the busiest node, with smaller values for nodes that take less load.

The actual weight used for a particular node is the per-node weight specified here, modified by the function defined by signalware.weight-function below. By default, all nodes have weight 100, and will receive an even proportion of incoming load.

signalware.weight-function

Defines the weight function applied to "full-rate" weights, to find the actual rate to use; can be used to gradually increase load on a newly-joined node without immediately swamping it with traffic.

The function is specified as a series of comma-separated values
S(1),T(1),S(2),T(2),…,S(N-1),T(N-1),S(N) where:

S(i) is the multiplier (in the range [0.0 .. 1.0]) of the "full-rate" weight to use in state (i)
T(i) is the total number of dialogs that must be received on a particular node before moving to state (i+1).

For example, the default specification of

0.01,10,0.10,1000,0.50,5000,1.00

defines a function:

for dialogs	state	use a weight of [ ] * per-node weight	(= % of normal load)
0-10	1	0.01	1%
11-1000	2	0.10	10%
1001-5000	3	0.50	50%
5000+	4	1.00	100%

If a node has a non-zero per-node weight, then the weight after applying the weight function is forced to be at least 1. Nodes with a zero per-node weight will always use a weight of 0.

signalware.fiber-map-size

Specifies the number of fibers used to process incoming messages. Larger values may provide more concurrency, but also increase memory usage slightly.

This property should not need modification unless you are tuning the TCAP fiber pool configuration. In that case, this value must be at least as large as the value of the
tcap-fibers.queue-size common RA property.

Changes to this property will only take effect when the RA entity is next activated.

signalware.dialog-allocation-timeout

Specifies the maximum time, in milliseconds, an SBB will block when waiting to create an outgoing dialog.

Occasionally, creation of a new outgoing dialog requires waiting for the backend process to allocate a new dialog identifier. The SBB creating the dialog will block while this happens. To prevent SBBs from blocking indefinitely, this property controls how long the RA will wait for the allocation to complete before giving up and throwing an exception to the calling SBB.

signalware.dialog-pool-size

Specifies the size of the dialog pool used to satisfy dialog creation requests.

The frontend maintains a pool of preallocated dialog identifiers so that it can immediately satisfy requests from an SBB for a new outgoing dialog without needing to block. This property controls the size of the pool.

The pool is refilled asynchronously to dialog requests. If the pool becomes empty, requests for new outgoing dialogs must block while the backend allocates a new dialog.

The preallocated dialogs count towards the per-backend dialog limit that applies to both incoming and outgoing dialogs. Each Rhino node allocates one pool per backend, so each backend in an N-node cluster may have up to N * signalware.dialog-pool-size dialogs reserved by these pools.

Increasing this value too much may cause backends to run out of available dialogs.