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 default configuration can usually be used without changes, except for two important properties:
|
Here are the configuration properties available in SGC.properties:
| Property | What it specifies | Default |
|---|---|---|
|
enables or disables the heartbeat timeout mechanism in the SGC. If this is enabled in the SGC then the TCAP stack must also be configured to send heartbeats, otherwise the connection between the TCAP stack and SGC will be marked as timed out after |
|
|
timeout (in seconds) waiting for a handshake between the SGC and TCAP stack |
|
|
how many seconds to wait before the Peer closes the connection after not receiving anything Value must be greater than the heartbeat period configured in the TCAP stack, see Data Connection Heartbeat Mechanism for details. |
|
|
capacity of the Peer sending queue |
|
|
whether to disable the Nagle algorithm for the connection between the SGC and TCAP stack |
|
|
whether to ignore the configured switch-local-address when establishing a client intra-cluster-communication (comm switch module) connection;
if
|
|
|
whether to disable the Nagle algorithm in intra-cluster communication client mode (comm switch module) |
|
|
number of threads serving connections (client mode) from other SGC nodes; for intra-cluster communication (comm switch module) Each thread requires three File Descriptors. The recommended value should be one less than number of nodes in the cluster. |
|
|
number of threads accepting connections from other SGC nodes; for intra-cluster communication (comm switch module) Each thread requires three File Descriptors. |
|
|
whether to disable the Nagle algorithm in intra-cluster communication server mode (comm switch module) |
|
|
number of threads serving connections (server mode) from other SGC nodes; for intra-cluster communication (comm switch module) Each thread requires three File Descriptors. The recommended value should be one less than number of nodes in the cluster. |
|
|
size of the socket receive buffer (in bytes) used by intra-cluster communication (comm switch module) Use a value <= |
|
|
size of the socket send buffer (in bytes) used by intra-cluster communication (comm switch module) Use a value <= |
|
|
number of threads accepting data connections from TCAP stack instances Each thread requires three File Descriptors. |
|
|
number of threads serving data connections from TCAP stack instances Each thread requires three File Descriptors. The recommended value should be equal to the number of TCAP stack instances served by the cluster. |
|
|
number of threads accepting connections from TCAP stack instances requesting balancing information |
|
|
number of threads serving accepted connections from TCAP stack instances requesting balancing information |
|
|
whether to try a graceful shutdown first (value true) when shutting down because of a uncaught exception |
|
|
how long to wait (in milliseconds) during graceful shutdown, before forcing a shutdown |
|
|
whether an uncaught exception should result in instance shutdown (value Severe errors ( |
|
|
optional path to the Hazelcast config file |
none, but the default |
|
cluster group to which this instance belongs |
|
|
implementation of the alarming factory |
|
|
maximum alarming history age (in minutes) |
|
|
property name used to get the path where the SGC data file should be stored |
current working directory at the time of startup |
|
property name used to get the actual SGC data file name |
|
|
whether the SGC should ignore validation of the MD5 signature of the XML configuration file |
|
|
maximum number of inbound messages that may be processing or waiting to be processed |
|
|
how long (in seconds) the SGC should consider a connection pending after peer node allocation, but before actual connection (after this time, the SGC assumes that the connection will not happen) This value is only by the Legacy 'ocss7.urlList' Connection Method to assist with balancing TCAP stacks amongst SGCs. If it is set too small then under certain failure conditions it may result in a TCAP stack continually trying to reconnect to an SGC data port that it cannot reach. The suggested value for this property is The default value allows for 13 TCAP stacks and 2 SGCs under worst case failure conditions with a 4 second safety factor. The safety factor allows for network latency and timer precision. |
|
|
maximum number of outbound messages that may be processing or waiting to be processed |
|
|
maximum number of TCAP peers/clients that may be concurrently connected to this SGC instance When selecting a value for this configuration property, it is important to take into account the following:
|
|
|
maximum number of migrated prefixes permitted to be handled by this SGC instance See Prefix Migration for a detailed description of prefix migration. A value of 0 disables prefix migration to this SGC. If prefix migration is enabled, the following points should be considered:
|
|
|
maximum number of tasks (messages to be processed) in one worker queue |
|
|
number of threads used by the worker group to process inbound and outbound messages |
|
|
counter file name for snmp4j |
|
|
file name for snmp4j persistent storage |
|
|
whether TCAP manager uses a Nagle algorithm for incoming connections |
|
|
name of the SGC instance within the cluster |
|
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, it is strongly recommend that the backup-count parameter is 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.
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>
...
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 id 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 |
