OCSS7 5.0 :: OCSS7 Installation and Administration Guide

On this page...

Configuration data
Managed SGC cluster configuration
- Configuration objects
- Common configuration object attributes

Configuration data

Configuration data can be separated into two main groups:

static — configuration properties loaded from a file during SGC instance start-up, influencing the behaviour of that single instance
managed — dynamic runtime configuration managed by and distributed within the SGC cluster.

SGC_HOME

In the following instructions, SGC_HOME represents the path to the SGC Stack installation directory.

Static SGC configuration

Static configuration is loaded during SGC instance startup; any configuration changes take effect after SGC Stack instance restart. Static configuration consists of:

static configuration properties
Hazelcast configuration
logging configuration.

Static SGC instance configuration

During SGC instance start-up, the SGC_HOME/config/SGC.properties configuration file is loaded.

The SGC.properties file may be modified using any standard text editor. This is a standard Java properties file containing one or more key-value pairs.

A full description of all of the configuration properties that may be set in SGC.properties may be found in Appendix A: SGC Properties.

An SGC restart is required if any of these properties are changed on a running SGC.

Configuration Properties of Particular Note

The majority of the configuration properties have default values that should not require changing. However, there are some whose values should be considered for each installation:

Property Presence Description

Property	Presence	Description
`ss7.instance`	mandatory	The name of the SGC instance. Must be unique amongst instances in the cluster.
`hazelcast.group`	mandatory for 2+ node cluster highly recommended for single node cluster due to small possibility of collisions	The name of the SGC cluster.
`sgc.tcap.maxTransactions`	optional	The default value is sufficient for most installation, but those installations expecting close to or greater than one million concurrent transactions may need to increase this value.
`backup.count`	mandatory for 3+ node cluster	The default value is sufficient only for 1 or 2 member clusters.

ss7.instance

mandatory

The name of the SGC instance. Must be unique amongst instances in the cluster.

hazelcast.group

mandatory for 2+ node cluster
highly recommended for single node cluster due to small possibility of collisions

The name of the SGC cluster.

sgc.tcap.maxTransactions

optional

The default value is sufficient for most installation, but those installations expecting close to or greater than one million concurrent transactions may need to increase this value.

backup.count

mandatory for 3+ node cluster

The default value is sufficient only for 1 or 2 member clusters.

Hazelcast cluster configuration

Hazelcast is a opensource In-Memory Data Grid. Hazelcast provides a set of distributed abstractions (such as data collections, locks, and task execution) that are used by subsystems of the SS7 SGC Stack to provide a single logical view of the entire cluster. SGC cluster membership state is directly based on Hazelcast cluster and node lifecycle.

The SGC stack deployment package uses a custom Hazelcast configuration, which is available in SGC_HOME/config/hazelcast.xml.sample.

The official Hazelcast documentation covering setting up clusters can be found in the Hazelcast 5.3 Reference Manual section Discovering Cluster Members.

Customizing Hazelcast Configuration

The Hazelcast configuration must be customized for your environment. This is done by providing a hazelcast.xml configuration file in the config subdirectory of the SGC Stack distribution (for example, by renaming config/hazelcast.xml.sample to config/hazelcast.xml). For a description of possible configuration options, and the format of the hazelcast.xml configuration file, please see the Hazelcast 5.3 Reference Manual section Hazelcast Configuration.

If you do not customize the Hazelcast configuration the cluster will fail to form.

Set the Hazelcast Bind Address

Specify the IP address and port that Hazelcast should bind to in advanced-network/member-server-socket-endpoint/interfaces/interface. For example, to configure a bind address of 192.168.1.89:15701:

<member-server-socket-endpoint-config>
    <interfaces enabled="true">
        <interface>192.168.1.89</interface>
    </interfaces>

    <port port-count="1" auto-increment="false">15701</port>

Wildcard addresses may also be used, for instance, 192.168.1.*.

Configure the Cluster Member Addresses

Specify the IP addresses (with port) that Hazelcast should connect to in order to discover other cluster members in advanced-network/join/tcp-ip/member/list/member. It is safe to specify the node’s own IP address and port here. For example, for a 2-node cluster:

<advanced-network enabled="true">
    <join>
        <tcp-ip enabled="true" connection-timeout-seconds="5">
            <member-list>
                <member>192.168.1.89:15701</member>
                <member>192.168.1.88:15701</member>
            </member-list>

Failure to include every node in the member-list may result in Hazelcast declaring a split brain on startup of cluster members. This will result in one or more SGC processes restarting in order to correctly resolve the split brain.

Hazelcast Heartbeat Configuration

The default Hazelcast configuration used by the SGC includes customisation of some hazelcast default values to support rapid cluster member failure detection and faster cluster merges following failure recovery. This configuration can be further refined as necessary.

Property What it specifies Default

Property	What it specifies	Default
`hazelcast.heartbeat.interval.seconds`	How frequently the hazelcast heartbeat algorithm is run.	`1s`
`hazelcast.max.no.heartbeat.seconds`	How long to wait before considering a remote hazelcast peer unreachable. If this value is set too small, then there is an increased risk of very short network outages or extended Java garbage collection triggering heartbeat failure detection. If this value is set too large, then there is an increased risk of SGC features becoming temporarily unresponsive due to blocking on necessary cluster-wide operations. It is important to balance the need to rapidly detect genuinely failed nodes with the need to protect against unnecessarily splitting and reforming the cluster as the split and merge operation is not instant and some SGC features may be temporarily unavailable during this process.	`5s`
`hazelcast.merge.first.run.delay.seconds`	How long hazelcast will wait to attempt a cluster merge immediately following a node failure.	`10s`
`hazelcast.merge.next.run.delay.seconds`	How long hazelcast will wait to attempt a cluster merge following a node failure after the first merge attempt.	`10s`

hazelcast.heartbeat.interval.seconds

How frequently the hazelcast heartbeat algorithm is run.

1s

hazelcast.max.no.heartbeat.seconds

How long to wait before considering a remote hazelcast peer unreachable.

If this value is set too small, then there is an increased risk of very short network outages or extended Java garbage collection triggering heartbeat failure detection.

If this value is set too large, then there is an increased risk of SGC features becoming temporarily unresponsive due to blocking on necessary cluster-wide operations.

It is important to balance the need to rapidly detect genuinely failed nodes with the need to protect against unnecessarily splitting and reforming the cluster as the split and merge operation is not instant and some SGC features may be temporarily unavailable during this process.

5s

hazelcast.merge.first.run.delay.seconds

How long hazelcast will wait to attempt a cluster merge immediately following a node failure.

10s

hazelcast.merge.next.run.delay.seconds

How long hazelcast will wait to attempt a cluster merge following a node failure after the first merge attempt.

10s

The hazelcast heartbeat mechanism is used to detect cluster member failures; either network failures between members or actual process failures.

Hazelcast Cluster With Three Or More Members

The default Hazelcast configuration used by the SGC is optimized for two cluster members. In the case where a larger cluster is required the hazelcast.backup.count SGC property must be configured to the total number of cluster members, minus one. This provides maximum resiliency in the case where more than one node may fail or be split from the cluster simultaneously.

If the hazelcast.backup.count is too low the cluster may suffer catastrophic data loss. This can lead to undefined behaviours up to and including total loss of service.

Configuration of the backup count is completed in SGC.properties using the hazelcast.backup.count property. The value from here is substituted at runtime into hazelcast.xml.

For a 2-node cluster this must be set to 1, i.e., the number of cluster members (2) - 1:

hazelcast.backup.count=1

For a 3-node cluster this must be set to 2:

hazelcast.backup.count=2

Logging configuration

For a description of the logging subsystem, please see Logging.

Managed SGC cluster configuration

The SS7 SGC Stack is built around a configuration subsystem that plays a central role in managing the lifecycle of all configuration objects in SGC. This is called "managed configuration" (when the configuration subsystem manages the configuration data). During normal cluster operation, configuration data and management state is shared between all cluster nodes. Each cluster node persists configuration data in the local file system (as an XML file).

Managed configuration can be divided based on its cluster or node-level applicability:

per node — this configuration is stored cluster-wide but relevant only for a given node (it references just the particular node for which it is relevant; for example, different SCTP associations may be created on specific nodes).
cluster wide — this configuration is relevant and the same for each node (general configuration parameters, SCCP configuration, parts of M3UA)

Configuration is represented as a set of configuration objects. These configuration objects are managed through a set of CRUD commands exposed by the Command-Line Management Console distributed with the SGC SS7 Stack.

Configuration objects

Each configuration object within the SS7 SGC Stack is an instance of a particular configuration object type. The type of configuration object defines a set of attributes. For example, configuration objects of type connection are defined by attributes such as port, conn-type, and others. A particular configuration object is identified by its oname attribute, which must be unique among all other configuration objects of that type.

Configuration objects may not be created, removed or altered when the SGC cluster is in an upgrade or reversion mode.

Common configuration object attributes

These attributes are common to some or all configuration objects.

oname	Every configuration object has an oname attribute that specifies its Object Name. It is an identifier that must be unique among all other objects of that particular type. Whenever an attribute is a reference to a configuration object, its value must be equal to the `oname` attribute of that referenced configuration object.
dependencies	A configuration object depends on another configuration object when any of its attributes reference that other configuration object. That is, the attribute value is equal to the `oname` attribute of the other configuration object. The configuration system keeps track of such references, and provides the `dependencies` attribute, which is a counter of how many other configuration objects depend on the current one. If the dependencies value is greater than `0`, the configuration object cannot be removed (to remove it, first all other configuration objects that depend on it must be removed).
enabled	Some configuration objects must be enabled before the configuration layer changes the related runtime state. All such objects expose the enabled attribute with values of `true` or `false`.
active	Some configuration objects with the enabled attribute also expose the active attribute, which tells if this object was successfully instantiated and is used in processing (for example if a connection is established). Possible values are `true` or `false`.

oname

Every configuration object has an oname attribute that specifies its Object Name. It is an identifier that must be unique among all other objects of that particular type.

Whenever an attribute is a reference to a configuration object, its value must be equal to the oname attribute of that referenced configuration object.

dependencies

A configuration object depends on another configuration object when any of its attributes reference that other configuration object. That is, the attribute value is equal to the oname attribute of the other configuration object. The configuration system keeps track of such references, and provides the dependencies attribute, which is a counter of how many other configuration objects depend on the current one.

If the dependencies value is greater than 0, the configuration object cannot be removed (to remove it, first all other configuration objects that depend on it must be removed).

enabled

Some configuration objects must be enabled before the configuration layer changes the related runtime state. All such objects expose the enabled attribute with values of true or false.

active

Some configuration objects with the enabled attribute also expose the active attribute, which tells if this object was successfully instantiated and is used in processing (for example if a connection is established). Possible values are true or false.