This document tells you how to install and administer the OpenCloud CGIN resource adaptor.

Note See the CGIN Statement of Compliance for a list of supported protocols and the CGIN Compatibility Guide for details on compatible platforms and software.

Topics

Configuring the Deployment File

Adding variables to deploy.properties

Deploying the CGIN RA

Manually or automatically deploying the RA

Administering the CGIN Resource Adaptor Entity

Setting the CGIN RA’s configuration properties.

Appendix A. Cluster upgrade procedures

Upgrading a cluster using the CGIN Signalware TCAP stack

Appendix B. Migrating to CGIN 1.5.x

Adapting to API and schema changes in CGIN 1.5.x.
Note

This book does not cover stack-specific configuration — for information on OpenCloud’s OCSS7, see the OCSS7 SGC TCAP Stack documentation, or for other stacks, see Using the Ulticom Signalware TCAP Stack, Using the Simulated TCAP Stack, and Using the teleSys MACH7 TCAP Stack).

Other documentation for CGIN can be found on the CGIN product page.

Configuring the Deployment File

The first step to installing the CGIN resource adaptor is to configure the deployment file.

Modify deploy.properties

Modify the file $CGIN_CONNECTIVITY_PACK_HOME/deploy.properties, using the following variables:

Variable Variable usage and description Example 
client.home

absolute path to a Rhino client installation; by default, this is set to assume that the CGIN connectivity pack was unpacked within an installed Rhino instance

 
client.home=${user.home}/RhinoSDK/client
 
cginra.properties

properties to use when deploying the CGIN RA; by default, this uses a simulated TCAP configuration

 
cginra.properties=​stack=​signalware,​signalware.​backends=turbine2:20146
Warning Both properties must be set.

The default deployment properties are:

# Configuration settings for deployment done by ant script deploy.xml

# client.home is the absolute path to the Rhino client installation.
# As released, this assumes that the CGIN connectivity pack has been
# installed as a subdirectory of the Rhino install.
# If that assumption is not correct, change this property to the right path.
client.home=${cgin.basedir}/../client

# The entity name used by the CGIN RA.
cginra.entityname=cginra

# cginra.properties contains the resource adaptor entity configuration properties
# that should be used to initialize the CGIN RA.
#
# Examples are provided for the OCSS7, Signalware and Simulated TCAP stacks.
#
# Only one of the following is required.

# The Simulated TCAP stack.
cginra.properties=stack=tcapsim,local-sccp-address="type=C7,ri=pcssn,pc=2,ssn=102",\
  tcapsim.listen-addresses=localhost:10102,tcapsim.remote-addresses=localhost:10101,tcapsim.sctp-stack=tcp

# The Signalware TCAP stack.
#cginra.properties=stack=signalware,signalware.backends=turbine2:20146

# The OCSS7 TCAP stack.
#cginra.properties=stack=ocss7,local-sccp-address="type=C7,ri=pcssn,pc=2,ssn=102",\
#  ocss7.sgcs=localhost:12201

# For the TeleSys MACH7 stack:
#cginra.properties=stack=mach7,local-sccp-address="type=C7,ri=pcssn,pc=2,ssn=102",\
#  mach7.backends=127.0.0.1:10102,mach7.slee-cluster-id=2,mach7.comm-mode=TCP,

Deploying the CGIN RA

Install the CGIN RA automatically by running the deployment script.

Run deploy.xml, under $CGIN_CONNECTIVITY_PACK_HOME/. For example:

$> ant -f deploy.xml
Warning If this is the first time you create and activate a CGIN RA entity for this installation of Rhino, the TCAP stack may require additional configuration or installation steps — please see the OCSS7 SGC TCAP Stack documentation, Using the Simulated TCAP Stack, Using the Ulticom Signalware TCAP Stack, or Using the teleSys MACH7 TCAP Stack.

Administering the CGIN Resource Adaptor Entity

To administer the CGIN resource adaptor entity, set the CGIN RA’s configuration properties.

For example:

$rhino-console> updateraentityconfigproperties cginra local-sccp-address=auto

Most configuration properties may be changed at any time, and will take immediate effect if the resource adaptor entity is active. A few properties, such as the type of TCAP stack used, will not take immediate effect if changed while the resource adaptor entity is active. In this case, an alarm will be raised to warn that changes will only take effect when the entity is next activated.

The RA has a set of universal properties that apply to all CGIN RA entities, and stack-specific properties that depend on the stack that a particular entity is using:

Information on specific configuration properties for each TCAP stack is available for:

For universal configuration properties, see below.

Universal configuration properties

These are the CGIN RA universal configuration parameters:

Parameter Usage and description 
stack

Short name of the TCAP stack to use. Can be one of

  • ocss7 - for the OpenCloud OCSS7 TCAP stack

  • signalware - for the Signalware TCAP stack

  • mach7 - for the teleSys MACH7 TCAP stack

  • tcapsim - for the simulated TCAP stack.

Note Changes to this property will only take effect when the entity is next activated. 
enabled-protocols

The list of protocols enabled in the RA; for example:

etsi_inap_cs1,cap_v1,cap_v2,cap_v3,cap_v4,map
 
default-activity-timeout

The default dialog activity timeout, measured in milliseconds. This specifies the initial dialog activity timeout used for newly created dialogs.

 
default-invoke-timeout

The default TCAP Invoke Timeout, measured in milliseconds. This specifies the invoke timeout for operations where the service has not provided an invoke timeout value.

 
local-sccp-address

Used for outgoing TC-BEGIN messages if no local SCCP address is explicitly provided by an SBB.

The address should be formatted in the format that com.opencloud.slee.resources.cgin.SccpAddressParser expects.
If this property has the value auto, then the TCAP stack will automatically determine an address to use.

Note See also SCCP Address Format details. 
relaxed-decoding

Boolean value specifying whether to relax the BER decoding rules to allow certain types of malformed data.

 
acn-inbound-aliases

For dialogs where CGIN is the dialog responder, configures the CGIN RA to accept the external application context name as a synonym for the internal application context name. Comma-separated list of values in <external OID>:<internal ASN.1> format.

To configure handling of cases where there is no dialog portion and hence no external application context name, use {} as the external OID. If all such cases should be aliased to the same application context, then the particular internal ASN.1 can be named, otherwise the protocol may provide an interceptor to determine the relevant application context. For example, {}:map.phase-1 configures handling of traffic with no dialog portions using the relevant MAP phase 1 application contexts.

 
acn-outbound-mappings

Comma-separated list of values in <internal ASN.1>:<external OID> format. For dialogs where CGIN is the dialog initiator, configures the CGIN RA to write the external OID in place of the internal application context name. A given internal ACN can be mapped to only one external OID. Several different internal ACNs can be mapped to the same external OID.
Note The following configuration properties configure the thread pool used to process incoming traffic. The parameters correspond to configuration of a java.util.concurrent.ThreadPoolExecutor instance. The default values are suitable for moderate load, but may need increasing for heavy load, or when dialog correlation is used. Monitor the CGIN.<entityname>.tcap-fibers stats parameter set to check the performance of the thread pool. 
tcap-fibers.max-pool-size

The maximum number of threads in the thread pool. If zero, then no thread pool is used.

 
tcap-fibers.queue-size

The maximum size of the queue used to store work waiting for processing by the thread pool. If the queue is full, then work is executed directly in the calling thread.

SCCP Address Format

Below are mandatory, point code — SSN, and global title parameters for the CGIN RA local-sccp-address configuration property.

Mandatory parameters

An SCCP address string must be formatted as comma-separated name/value pairs. The following parameters are mandatory:

Parameter Description Valid values 
type

SCCP address type

A7, C7, CH7, or J7

 
ri

Routing indicator

gt, pcssn, or ssn (pcssn and ssn are equivalent.)

Point code — SSN parameters

Parameter Description Valid values 
pc

Point code

Formatted as either:

  • a single decimal value in the range 0-16777215 (= 0xffffff), which supports all addressing formats up to 24-bits long expressed as a single number

  • a / separated triple:

    • If type=C7 has been specified, an x/y/z triple is taken to mean the 3/8/3 bit fields of the zone/area/signal point address format.

    • If type=A7 or type=CH7, an x/y/z triple is taken to mean the 8/8/8 bit fields of the member/cluster/network address format.

 
ssn

Subsystem number

in the range 0-255

Global title parameters

Parameter Description Valid values 
digits

Global title address digits

 
nature

Global title nature of address indicator

unknown, international, national, subscriber, or a decimal value in the range 0-15

 
numbering

Global title number plan

unknown, isdn, generic, data, telex, maritime-mobile, land-mobile, isdn-mobile, private, or a decimal value in the range 0-15

 
tt

Global title translation type

in the range 0-255

 
national

Global title national indicator

true or false

 
gti

Global title indicator

  • If not included, this parameter will be calculated automatically.

  • If present, this parameter will be validated against the expected value (based on the other parameters in the address).

Global title rules

When specifying global titles, the following rules apply:

  • Global title parameters are only included in the returned address if digits is specified.

  • The global title indicator used depends on the SCCP address and parameter values, as follows:

For these SCCP addresses: If these values are specified: This global title indicator is used:

C7, J7, and CH7

nature only

 
GT_0001

tt only

 
GT_0010

numbering and tt

 
GT_0011

nature and either or both of numbering and tt

 
GT_0100

unspecified

The number plan defaults to unknown and the translation type defaults to 0.

A7

tt only

 
GT_0010

tt and numbering

 
GT_0001

For example:

type=c7,ri=pcssn,pc=4012,ssn=123
type=c7,ri=pcssn,pc=1/245/7,ssn=123
type=c7,ri=gt,digits=34607012345,nature=national,national=true

Appendix A. Cluster Upgrade Procedures

This page includes instructions for doing a live upgrade from an existing Rhino cluster that is receiving traffic through CGIN, to a new cluster that has the same configuration but different software versions (such as a new Rhino or CGIN version, or new service version if it can’t be done in a single cluster).

Below are general information about and then instructions for performing upgrades using STP redirection, and Signalware In-place upgrades.

About cluster upgrades with CGIN

Below is a table of possible upgrade paths for clusters using the CGIN Signalware TCAP stack:

Old version New version Upgrade using STP redirect? Upgrade in-place? 
1.4.x
 
1.5.x

Yes

Yes

 
1.5.x
 
1.5.x

Yes

Yes
Warning
A warning about ETC/ARI dialog correlation

ETC/ARI dialog correlation arranges for inbound ARI dialogs to be directed to the same cluster node that sent the corresponding ETC. In general, dialog correlation can only happen within a single cluster. During an upgrade, there are two clusters present and receiving traffic.

If an ARI dialog is received by the "wrong" cluster (a cluster that did not send the corresponding ETC), then correlation will fail, and the ARI will not be directed to the correct cluster node. If dialog correlation is used, then care should be taken to ensure that ARI dialogs are directed to the correct cluster — for example, by configuring the service deployed in the new cluster to send ETCs that direct the ARI dialogs to an SCP address associated with the new cluster only.

Upgrades using STP redirection

Note

This approach manages the upgrade externally to Rhino and Signalware, and requires support from the STP and surrounding network, as well as support in the existing service.
It can be used for all types of upgrade.

Prerequisites

Before upgrading using STP redirection, make sure that:

  • Inbound TC-BEGINs are addressed to a "logical" GT. The STP translates this GT to one-of-N "physical" addresses using a load-balancing mechanism. These "physical" addresses route to a particular cluster.

  • The STP needs the ability to reconfigure the translation addresses in use at runtime.

  • The old and new clusters are assigned different "physical" addresses.

  • The service ensures that initial responding TC-CONTINUEs provide an SCCP Calling Party Address that is the "physical" address for the cluster that is responding.

  • Subsequent traffic uses the "physical" address using normal TCAP procedures.{note}

Upgrade process

To upgrade using STP redirection:

1

Set up the new cluster with a new "physical" address.

2

Configure and activate the new cluster.

3

Reconfigure the STP to include the new cluster’s physical address when translating the logical GT.

4

Verify that traffic is processed by the new cluster correctly.

5

Reconfigure the STP to exclude the old cluster’s physical address when translating the logical GT.

6

Wait for all existing dialogs to drain from the old cluster.

7

Halt the old cluster.

Signalware In-place upgrade procedure

Note

This upgrade process supports upgrades where the service in use may initiate outbound CGIN dialogs.
It is supported when using Signalware for upgrades from CGIN 1.4.x to 1.5.x and from 1.5.x to 1.5.x

1
Set up the new cluster

  • Install the new cluster. Ensure that the cluster ID used is different to that of the old cluster, and that files, databases, and ports used by the new cluster don’t overlap with the old cluster.

  • Boot the new cluster.

  • Ensure that Rhino is in the STOPPED state

  • Deploy and configure RAs and services. Configure CGIN RA entities in the same way as on the "old" cluster, pointing to the same backend addresses.

Tip A Rhino export from the old cluster may be useful for this step.

Now you should have the "new" cluster configured, but STOPPED, so that it is not receiving traffic.

Caution To roll back this step, just discard your new cluster install. (No traffic is being processed by the new cluster yet.)

2
Start the new cluster

  • To start the "new" cluster, change the SLEE state to RUNNING. The new cluster RAs will connect to the same backends as the old cluster. New incoming traffic will be loadbalanced between the old and new clusters.

Note Initially, not much traffic will be loadbalanced to the new cluster. With the default settings, initially only 1% of traffic will be allocated to the new cluster; so at low call rates, it may take some time before traffic is processed by the new cluster.

  • Verify that the new cluster is processing calls correctly.

Caution

To roll back this step:

  1. Reconfigure each CGIN resource adaptor entity in the new cluster to set the RA property signalware.base-weight to 0. For example:

    updateraentityconfigproperties entityname signalware.base-weight=0

  2. Wait for all dialogs in the new cluster to end.

  3. Stop the new cluster — change the SLEE state to STOPPED.

3
Drain calls from the old cluster

  • For each CGIN RA entity in the old cluster, reconfigure the RA entity to set the RA property signalware.base-weight to 0:

    updateraentityconfigproperties entityname signalware.base-weight=0

At this point, all new dialogs will be directed to the new cluster only. The old cluster will only continue to process existing dialogs established before the draining process started.

  • Wait for all dialogs in the old cluster to end.

Now the old cluster should be still connected to the CGIN backends, but completely idle — no traffic is being handled by the old cluster.

Caution To roll back this step, for each CGIN RA entity in the "old" cluster, reconfigure the RA entity to restore the original value of signalware.base-weight, by default 100.

4
Stop the old cluster

  • Stop the SLEE using the stop management command.

  • Wait for the SLEE to reach the STOPPED state.

Caution To roll back this step, start the SLEE.

5
Shut down the old cluster

  • Shut down the old cluster using the shutdown management command.

Caution To roll back this step, restart the "old" cluster processes.

6
Schedule upgrade of old backends to the new version

(if needed)

Appendix B. Migrating to CGIN 1.5.x

Here are some things to note when migrating to CGIN 1.5x:

When…​ Do this:

Upgrading from a CGIN older than 1.4.x

First upgrade to 1.4.0 using the process described in Appendix B of the CGIN 1.4 Installation and Configuration Guide.

Using the API

Review the revised service code to the 1.5.x API. For an informal summary of API changes, please see the Changelog. For details of the new API, see the Javadoc.

Migrating Scenario files to the current schema version

Note that the Scenario Simulator IN Scenario Pack’s schema has changed for this release. The Scenario Editor provides support for automatically migrating scenarios to the latest IN Scenario Pack schema version, please see the --migrate option under Command-line options in the Scenario Editor User Guide.

Configuring the RA

If you’ve been using CGIN 1.4.x, note that the configuration property acn-mappings no longer exists. It has been subsumed by the new configuration properties acn-inbound-aliases and acn-outbound-mappings — see Administering the CGIN Resource Adaptor Entity.