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, |
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 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:
ss7.instance |
mandatory | The name of the SGC instance. Must be unique amongst instances in the cluster. |
|---|---|---|
mandatory for 2+ node cluster |
The name of the SGC cluster. |
|
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. |
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 3.7 Reference Manual section Setting Up Clusters.
Hazelcast configuration can be customized 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 3.7 Reference Manual section Understanding 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 |
|---|---|---|
|
How frequently the hazelcast heartbeat algorithm is run. |
|
|
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. |
|
|
How long hazelcast will wait to attempt a cluster merge immediately following a node failure. |
|
|
How long hazelcast will wait to attempt a cluster merge following a node failure after the first merge attempt. |
|
The hazelcast heartbeat mechanism is used to detect cluster member failures; either network failures between members or actual process failures.
The default Hazelcast configuration used by the SGC is optimized for two cluster members. In the case where a larger cluster is required the backup-count parameter 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 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.
|
There are multiple locations within hazelcast.xml where this parameter must be configured: under <queue name="default">, <map name="default">, <multimap name="default">, <list name="default">, <set name="default">, <semaphore name="default"> and <ring-buffer name="default">. Each of these must be configured for correct behaviour.
For example, in a three node cluster:
<queue name="default">
<max-size>10000</max-size>
<backup-count>2</backup-count>
...
<map name="default">
<in-memory-format>BINARY</in-memory-format>
<backup-count>2</backup-count>
...
<multimap name="default">
<backup-count>2</backup-count>
...
<list name="default">
<backup-count>2</backup-count>
...
<set name="default">
<backup-count>2</backup-count>
...
<semaphore name="default">
<initial-permits>0</initial-permits>
<backup-count>2</backup-count>
...
<ring-buffer name="default">
<capacity>10000</capacity>
<backup-count>2</backup-count>
...
On a host with multiple network interfaces it is necessary to manually specify the network interface(s) to bind to in the network/interfaces section of hazelcast.xml.
If this is not manually specified then Hazelcast will select an arbitrary interface at boot. This may result in the node starting up as a singleton — unable to communicate with the other cluster members.
For example:
<network>
<interfaces enabled="true">
<interface>192.168.1.*</interface>
</interfaces>
<network>
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.
|
See also
Command-Line Management Console
|
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.
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 |
|---|---|
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 If the dependencies value is greater than |
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 |
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 |
