This document explains how to configure CGIN to use the teleSys MACH7 TCAP stack.

Topics

This document includes the following topics:

About the teleSys MACH7 Stack Implementation

The teleSys MACH7 stack is a third-party TCAP stack implemented by teleSys, for use with their MACH7 TCAP implementation.

OpenCloud distributes the teleSys MACH7 stack with CGIN v1.4.2 and above.

Software architecture

Note For details on the teleSys MACH7 software architecture please see the Software Architecture document from teleSys.

Backend configuration

Note For details on configuring teleSys MACH7 backends, please see documentation from teleSys.

Installing the TCRA

The teleSys MACH7 TCRA is a software component provided by teleSys which, when installed into CGIN, allows CGIN and the Scenario Simulator to use the teleSys MACH7 TCAP stack.

The teleSys MACH7 TCRA and CGIN

The TCRA provides the CGIN-side, front-end component of the MACH7 stack, and is responsible for communicating with the MACH7 backend servers.

Beginning with CGIN 1.5.0.19 the TCRA is no longer built into CGIN. Instead, an installation script and a default version of the TCRA are included with CGIN. Customers may install the TCRA included with CGIN, or a different version of the TCRA, if required. The installation script has been tested with and is known to work with the version of the TCRA included with CGIN. If the installation procedure for the desired version of the TCRA differs from that of the TCRA included with CGIN then the script may not work and it may be necessary to install the desired TCRA manually using the instructions provided by teleSys.

OpenCloud installation script for teleSys MACH7 RA

The install-mach7.sh script automates the instructions provided by teleSys to insert the MACH7 TCRA into the CGIN Unified RA deployable unit and into the CGIN protocol adaptor used by the bundled Scenario Simulator. Documentation for this script is provided below.

If you would like to use SCTP as a transport protocol between CGIN and the MACH7 server then you may also wish to read Using SCTP, which documents SCTP set up and configuration.

Where and when to run the MACH7 installation script

If desired, this script should be run once:

  • before deploying the CGIN Unified RA; or

  • in any newly unpacked CGIN copy which requires the Scenario Simulator to communicate via the teleSys MACH7 stack.

CGIN can be zipped back up after running the MACH7 installation script, if desired, allowing the installation script to be run on systems other than the one on which CGIN will eventually be deployed into Rhino.

Requirements

  • CGIN unpacked

  • Perl

  • Oracle JVM 1.5 or newer

  • Bash

  • (optional, unsupported) A different version of the MACH7 TCRA than that shipped with CGIN, unpacked somewhere.

Installation

Run the installer script:

bash install-mach7.sh

The script will attempt to automatically determine the location of required components. If these components cannot be found it will prompt for their location.

It will prompt for the location of the TCRA to be installed, defaulting to the one distributed with this version of CGIN.

The CGIN unified RA DU and the CGIN unified RA implementation jar inside that DU will then be patched with the M7TCRA.

If the CGIN unified RA has already been deployed then it MUST be redeployed after installation is complete.

Non-interactive installation

To successfully run the installer in non-interactive mode the installer needs to be able to find all required components in their default locations. Specifically:

  • unzip, zip, tar, gunzip and perl must all be in the default PATH

  • The MACH7 TCRA must be unpacked into telesys/files/ and must be the only MACH7 TCRA there. The installer will install the first M7TCRA matching the pattern $SCRIPT_DIR/files/M7TCRA_*.

Run the installer script with the -a option:

bash install-mach7.sh -a

Installing a custom version of the MACH7 TCRA

If you wish, you may provide the location of an alternate version of the MACH7 TCRA when asked for the location of the TCRA. The installer will make a "best efforts" attempt to install that version.

Warning

Different releases of the TCRA may require different installation procedures than those carried out by the script, and as such we cannot guarantee that any version of the TCRA other than that distributed with CGIN will successfully install.

In the case where the installation script fails it will be necessary for you to install the TCRA manually into the CGIN deployables following the installation instructions provided by teleSys.

Configuring the CGIN Frontend

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

Tip
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 teleSys MACH7 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 teleSys MACH7 TCAP stack, set stack=mach7.

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

Configures which backend processes to connect to.

Must be specified when the teleSys MACH7 TCAP stack is used. The property is a comma-separated list of ip:port values identifying the backend TCP/SCTP ports to connect to. The IP and port should correspond to the configured backend process IP address 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.

 
mach7.slee-cluster-id

Uniquely identifies the cluster that this RA entity belongs to.

Must be specified when the teleSys MACH7 TCAP stack is used. The property is an integer value that uniquely identifies the cluster that this RA entity belongs to. It does not need to match the SLEE’s cluster ID, but should be distinct from the value used by RA entities belonging to another cluster.

 
mach7.sccp-bind-address

Configures the SCCP bind address to be used.

This configuration property may be used to specify the SCCP bind address. If PC and SSN fields are present in the local-sccp-address property, then they do not need to be present in the mach7.sccp-bind-address property.

Tip You can still provide network appearance (nwApp) information.

Any PC or SSN setting in mach7.sccp-bind-address must match that used in
local-sccp-address. For example:

mach7.sccp-bind-address="pc=2057,ssn=2,nwApp=0"
mach7.sccp-bind-address="nwApp=1"
 
mach7.corr-cluster-id

Used for advanced routing through the AN for correlated messages.

This configuration property is used by the ASC process to register with the AN as part of a cluster. This value is used for advanced routing through the AN for correlated messages.

 
mach7.comm-mode

Configures the frontend↔backend communication protocol.

This configuration property controls the protocol used for communication between the frontend and backend processes. Possible values are "SCTP" and "TCP". The default value is "SCTP".

Warning You need to adjust Rhino’s configuration to use SCTP communication mode — see Using SCTP. 
mach7.node-id

Configures the Scenario Simulator node ID.

This configuration property can only be set when using the Scenario Simulator. It is used to distinguish between multiple scenario simulator instances belonging to the same mach7.slee-cluster-id. In the CGIN RA, the teleSys MACH7 stack uses the Rhino Node ID instead; and this property cannot be set.

Using SCTP

The telesys MACH7 Stack frontends may communicate with the backends using either TCP or SCTP. Both frontend and backend must be configured to use the same protocol.

Warning SCTP support is currently only available for RedHat EL5 on x86_64.

Configuring the telesys MACH7 Stack to use SCTP

There are three stages to configuring SCTP:

  1. Configure the MACH7 backend process to use SCTP — see the teleSys documentation.

  2. Set mach7.comm-mode to SCTP in the frontend — see Configuring the CGIN Frontend.

  3. Adjust the Rhino or Scenario Simulator configuration — see below.

Adjusting Rhino and/or Scenario Simulator configuration

OpenCloud provides the script install-mach7-sctp.sh which automates the instructions provided by teleSys to configure their TCAP stack to support SCTP.

Note that this script does not perform Mach7 TCRA installation into CGIN; see Installing the TCRA for details.

Where and when to run the SCTP Support installation script

If desired, this script should be run:

  • before Rhino cluster creation, in the Rhino installation directory which will be used to create the cluster; or

  • after Rhino cluster creation, in all Rhino installation directories on all servers in the cluster; or

  • in any newly unpacked CGIN copy which requires the Scenario Simulator to communicate via SCTP with the teleSys Mach7 stack.

Requirements

  • RedHat Linux x86_64 with the following packages installed:

    • lksctp-tools-1.0.6-3.el5

    • lksctp-tools-devel-1.0.6-3.el5

    • lksctp-tools-devel-1.0.6-3.el5

    • lksctp-tools-1.0.6-3.el5

  • Rhino (SDK or Production) 2.3

  • CGIN unpacked, and already patched using install-mach7.sh (see Installing the TCRA for details).

  • patch and bash.

Installation

Run the installer script:

bash install-mach7-sctp.sh

The script will prompt for information, including the location of RHINO_HOME.

Rhino will then be configured (including any pre-existing nodes) for use with teleSys SCTP.

A restart of Rhino is REQUIRED after installation is complete.

Non-interactive installation

To successfully run the installer in non-interactive mode CGIN must be unpacked in Rhino’s base directory. That is, RHINO_HOME will lie two directories down from the install-mach7-sctp.sh script:

RHINO_HOME/cgin-connectivity-[version]/telesys/install-mach7-sctp.sh

Run the installer script with the -a option:

bash install-mach7-sctp.sh -a