This page describes how Sentinel IP-SM-GW uses the Cassandra database.
Overview
The IPSMGW uses a Cassandra database for storing Third Party Registration data, Routing Information, and for generating Message References. During Installation the user is asked to enter connection details for the Cassandra Database.
How it works
The Cassandra Storage system uses the Cassandra CQL RA to create, update and remove entries from a Cassandra Database cluster.
For information about the Cassandra CQL RA’s architecture and configuration, see the Cassandra CQL Resource Adaptor Guide. |
Cassandra Database Configuration
The administrator is required to download and set up a Cassandra Database.
The Sentinel IP-SM-GW installer does not perform this function on the behalf of the user.
It is required that the installed version of Cassandra be 2.0.17+ or 2.1.17+
.
OpenCloud recommends reading Cassandra’s Getting Started page.
For a test system, a single Cassandra Database instance may be sufficient if redundancy is not a requirement.
Minimal production recommendations
For a minimal production system, in order to tolerate a single failure in the Cassandra Database there should be at least three nodes configured per site. The Cassandra replication factor should be three.
Higher replication factors can be used on larger clusters.
The recommended consistency level for this storage system is the LOCAL_QUORUM
consistency level.
All read and write queries are programmed to use LOCAL_QUORUM
as the consistency level.
It is assumed that in a multi-site deployment, an appropriate Snitch
and Topology Strategy are used.
As a basis, we suggest use of the NetworkTopologyStrategy
and GossipingPropertyFileSnitch
, then reading the relevant links below to review this selection.
There are several recommended links to review when planning a deployment.
Configuration aspect | Cassandra documentation link |
---|---|
Planning a Cassandra deployment |
|
Recommended settings for Cassandra |
|
Some anti-patterns, or things to not do with Cassandra |
|
Cassandra Consistency levels and replication factors - in particlar read the LOCAL_QUORUM section |
|
Cassandra Snitches - read this when configuring a single site or multi-site deployment |
|
Cassandra Topology Strategies - read this when configuring a single site or multi-site deployment |
Performance recommendations
OpenCloud recommend that Cassandra’s Data directory and Commit log directories are on different physical devices (e.g. different disks). If this is not possible, then different partitions on the same device is acceptable. OpenCloud performance testing shows that there are benefits using different partitions on the same device when there are 1000 or more Cassandra DB transactions per second.
Setting the tombstone deletion strategy to a shorter interval than the default is strongly recommended for third-party registration tables. The default interval causes increased load on the Cassandra servers during compaction, and particularly during recovery after failover. 1 hour is sufficient for proper management of registration and session data. Set the gc_grace_seconds configuration parameter to 3600 to delete tombstone records after 1 hour. Other compaction configuration parameters may assist in the timely deletion of tombstone records.
Sentinel IP-SM-GW Configuration for Cassandra
Each insert and update in the database uses Cassandra’s 'time to live' feature, automatically removing stale data from the database. The TTL is set in seconds. It is always calculated to be greater than the largest expiry for a First Party Registration.
3rd-Party Registration TTL
The TTL is defined as the largest expiry from First Party Registration plus a configured time.
The configured time value is defined in the Profile Table CassandraSubscriberDataStoreConfig
.
It is scoped by a Sentinel Selection Key.
The value is stored in the attribute named CassandraTTL
.
The default value is 1800 seconds (30 minutes).
Routing Info TTL
For Routing Info the TTL is configured in IPSMGWRoutingInfoCassandraConfigProfileTable.
The value is stored in the attribute named CassandraTTL
.
The default value is 120 seconds.
Sentinel IP-SM-GW Data Schema
Cassandra’s tables exist in a 'keyspace', which, for illustrative purposes, can be thought of as a 'database' in SQL implementations. Creating a keyspace is simple, but some considerations are present.
Third Party Registration
-
The keyspace must be named
opencloud_thirdparty_reg
-
For a production environment, the keyspace can be created such that it is replicated. A sample CQL command for creating such a keyspace is:
CREATE KEYSPACE opencloud_thirdparty_reg WITH REPLICATION={'class' : 'NetworkTopologyStrategy' ,'replication_factor' : 3 };
-
For testing purposes, replication may not be necessary. A sample CQL command for creating such a keyspace is:
CREATE KEYSPACE opencloud_thirdparty_reg WITH REPLICATION={'class' : 'SimpleStrategy' ,'replication_factor' : 1 };
Once a keyspace is created, the required tables can be created. The following CQL statements provide both the structure and insight into the tables that are required.
USE opencloud_thirdparty_reg;
CREATE TABLE REGISTRATIONDATA(
callid text, //The callid used for registration
defaultpublicid text, //The default IMS Public ID
privateid text, //The IMS Private ID
associateduris list<text>, //The Associated URIs
contacts set<text>, //Registered Contacts
visitednetworkid text, //P-Visited-Network-ID header from registration
creationtime timestamp, //The registration creation datetime
expires int, //The time this registration expires in seconds
expirytime timestamp, //The registration expiration datetime
tempgruu text, //Temporary GRUU defined in the Contacts
gruu text, //The GRUU in the Contacts
cmsisdn text, //The Correlation MSISDN
stnsr text, //The Session Transfer Number for Single Radio
isuesrvcccapable boolean, //Whether the ue has capability UE-SRVCC-CAPABILITY-SUPPORTED
paccessnetworkinfo list<text>, //P-Access-Network-Info header from registration
currentatusti text, //Current ATU-STI, from initial registration
atcfmgmturi text, //ATCF Management URI, from initial registration
atcfpathuri text, //ATCF path URI, from initial registration
primary key(callid)
) WITH gc_grace_seconds = 3600;
CREATE TABLE ASSOCURIS(
impu text, //A referenced IMS Public ID
callid text, //The callid used for registration
isdefault boolean, //Flag indicating if this IMPU is the default public ID
defaultpublicid text, //The default IMS Public ID
privateid text, //The IMS Private ID
regstate text, //Registration state: active, terminated or unknown
creationtime timestamp, //The registration creation datetime
expires int, //The time this registration expires in seconds
expirytime timestamp, //The registration expiration datetime
cmsisdn text, //The Correlation MSISDN
associateduris list<text>, //The Associated URIs
contacts set<text>, //Registered Contacts
isuesrvcccapable boolean, //Whether the ue has capability UE-SRVCC-CAPABILITY-SUPPORTED
visitednetworkid text, //P-Visited-Network-ID header from registration
paccessnetworkinfo list<text>, //P-Access-Network-Info headers from registration
currentatusti text, //Current ATU-STI, from initial registration
atcfmgmturi text, //ATCF Management URI, from initial registration
atcfpathuri text, //ATCF path URI, from initial registration
primary key(impu,callid)
) WITH gc_grace_seconds = 3600;
Setting the tombstone deletion strategy to a shorter interval than the default is strongly recommended for third-party registration tables. The default interval causes increased load on the Cassandra servers during compaction, and particularly during recovery after failover. 1 hour is sufficient for proper management of registration and session data. Set the gc_grace_seconds configuration parameter to 3600 to delete tombstone records after 1 hour. Other compaction configuration parameters may assist in the timely deletion of tombstone records but are usually not required.
To set the gc_grace_seconds parameter for REGISTRATIONDATA run the CQL command
ALTER TABLE REGISTRATIONDATA WITH gc_grace_seconds = 3600;
IP-SM-GW Routing Information
-
The keyspace must be named
opencloud_ipsmgw_routing_info
-
For a production environment, the keyspace can be created such that it is replicated. A sample CQL command for creating such a keyspace is:
CREATE KEYSPACE opencloud_ipsmgw_routing_info WITH REPLICATION={'class' : 'NetworkTopologyStrategy' ,'replication_factor' : 3 };
-
For testing purposes, replication may not be necessary. A sample CQL command for creating such a keyspace is:
CREATE KEYSPACE opencloud_ipsmgw_routing_info WITH REPLICATION={'class' : 'SimpleStrategy' ,'replication_factor' : 1 };
Once a keyspace is created, the required tables can be created. The following CQL statements provide both the structure and insight into the tables that are required.
USE opencloud_ipsmgw_routing_info;
CREATE TABLE IPSMGWROUTINGINFO(
mtcorrelationid text, //The mtcorrelationid used as the address of the SRI SM response
appcontext text, //The application context of the stored SRI SM response
srismarg blob, //The SRI SM request that is stored as a byte array
srismres blob, //The SRI SM response that is stored as a byte array
msisdn text, //The MSISDN retrieved from the SRI SM request
imsi text, //The IMSI retrieved from the SRI SM response
primary key(mtcorrelationid)
) WITH gc_grace_seconds = 3600;
CREATE TABLE IPSMGWGenerateMessageReference(
imsi text, //MSISDN from the MT FSM (previously used IMSI as key, but not always available)
messagereference bigint, //The message reference counter to use when forwarding an RpData - it will be modulo 256 so we actually loop through 0 - 255
primary key(imsi)
) WITH gc_grace_seconds = 3600;
The schemas are used by three features: