Note This document provides a high-level overview of Sentinel Registrar.

Topics

This document introduces the OpenCloud Sentinel Registrar:

Audience and Scope

Intended Audience

This document is aimed at network operators, systems integrators, and software developers.

Scope

This document provides an overview of the OpenCloud Sentinel Registrar product.

Introducing Sentinel Registrar

The Sentinel Registrar

The Sentinel Registrar is a third-party registrar used with the Sentinel VoLTE platform.

sentinel registrar and volte
Sentinel Registrar and the Sentinel VoLTE platform

The Sentinel Registrar is triggered by the CSCF during the UE registration process, based on the iFC (initial filter criteria) configuration for the subscriber in the Cassandra database. The CSCF triggers the Sentinel Registrar with a SIP REGISTER message that includes, in the message body, the first-party REGISTER request and response.

sentinel registrar
Sentinel Registrar in context

The Sentinel Registrar processes both the third-party REGISTER request and the encapsulated first-party REGISTER request and response, before it sends a SIP response to the CSCF.

Inside Sentinel Registrar

Inside the Registrar

The Sentinel Registrar is built using features and mappers on the enhanced Sentinel SIP core.

Tip

See Sentinel Overview and Concepts for an introduction to the Sentinel platform.

In particular, refer to Feature Execution Scripts, Features, Mappers.

Sentinel Registrar is part of the Sentinel VoLTE installation. The Registrar defines a session plan for processing REGISTER requests that defines a number of points-in-session where REGISTER requests are processed by registrar features and registrar mappers.

Third Party Registration state is persisted into a Registrar Data Store that is an external system with suitable characteristics to store Third Party Registration information. The default implementation of the Registrar Data Store uses a Cassandra Database.

Sentinel Registrar creates, updates and removes registration related information (such as registered identities, IMS Private Identities, GRUUs, C-MSISDN and so-on) as SIP User Agents Register, Re-Register and De-Register. The Registrar Data Store is consulted during INVITE processing by the Sentinel VoLTE Service.

Cassandra storage

Overview

The Registrar has an extensible storage system for Third Party Registration data. The default storage system uses a Cassandra Database cluster.

How it works

The Cassandra Storage system uses the Cassandra CQL RA to create, update and remove entries from a Cassandra Database cluster.

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.

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).

Note 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 VoLTE 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.

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. Please refer to Cassandra documentation for clusters larger than three and appropriate replication factors. 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.

Planning a Cassandra deployment

http://docs.datastax.com/en/cassandra/2.0/cassandra/architecture/architecturePlanningAbout_c.html

Recommended settings for Cassandra

http://docs.datastax.com/en/cassandra/2.0/cassandra/install/installRecommendSettings.html

Some anti-patterns, or things to not do with Cassandra

http://docs.datastax.com/en/cassandra/2.0/cassandra/architecture/architecturePlanningAntiPatterns_c.html

Cassandra Consistency levels and replication factors - in particlar read the LOCAL_QUORUM section

http://docs.datastax.com/en/cassandra/2.0/cassandra/dml/dml_config_consistency_c.html

Cassandra Snitches - read this when configuring a single site or multi-site deployment

http://docs.datastax.com/en/cassandra/2.0/cassandra/architecture/architectureSnitchesAbout_c.html

Cassandra Topology Strategies - read this when configuring a single site or multi-site deployment

http://docs.datastax.com/en/cassandra/2.0/cassandra/architecture/architectureDataDistributeReplication_c.html

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.

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.

  • The keyspace must be named opencloud_thirdparty_reg

  • For a production environment, and for non-functional testing prior to production, the keyspace is created such that it is replicated. A sample CQL command for creating such a keyspace is:

CREATE KEYSPACE IF NOT EXISTS opencloud_thirdparty_reg WITH REPLICATION={'class' : 'SimpleStrategy' ,'replication_factor' : 3 };

  • When developing features using the SDK against Cassandra, replication may not be necessary. A sample CQL command for creating such a keyspace is:

CREATE KEYSPACE IF NOT EXISTS 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 IF NOT EXISTS 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
    extensions map<text,text>,      //Extensions map
    primary key(callid)
)
WITH gc_grace_seconds = 172800; // 2 days

CREATE TABLE IF NOT EXISTS 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
    extensions map<text,text>,      //Extensions map used to store PATH information
    primary key(impu,callid)
)
WITH gc_grace_seconds = 172800; // 2 days

Statistics

The statistics are updated during the processing of the feature.

Parameter …​ incremented if …​

FailedToPrepareCassandraStatement

Can not prepare a statement to submit to database.

FailedToExecuteCassandraStatement

Can not execute a statement in database.

FailedToReadCassandraResultSet

Can not access the result of statement execution.

NoRegistrationDataFound

No registration data found to the specified callid.

RegistrationDataExpired

The registration data found is expired.

RegistrationDataFound

Found a valid registration data.

AddNewPAssociatedURI

Could add a new P-Associated URI.

RefreshInactivePAssociatedURI

A P-Associated URI is updated to the new expire date on a re-registration event.

TerminatePAssociatedURI

Could set a P-Associated URI to terminate state.

DeleteRegistrationData

Could delete the subscriber data.

ActivatePAssociatedURI

Could set a P-Associated URI to active state.

For Third Party Registration, the statistics are tracked by the sentinel.registrar SBB and can be found using the parameter set SLEE-Usage.Services.ServiceID[name=sentinel.sip,vendor=OpenCloud,version=3.1.0].SbbID[name=registrar.subscribers.cassandra,vendor=OpenCloud,version=3.1.0]

Registrar Features

The Registrar is built using the enhancements for Sentinel SIP. All registrar features communicate with the Sentinel SIP core using the SentinelSipMultiLegFeatureEndpoint endpoint interface.

A registrar feature may request that the first-party REGISTER request is refused by setting the RejectRegisterRequest session state field defined in the com.opencloud.sentinel.state.SentinelRegistrarSessionState interface.

// mark that the REGISTER should be rejected
getSessionState().setRejectRegisterRequest(true);

This session state field may be inspected in feature exection scripts to choose what features should run and ultimately if the third party REGISTER request is accepted or rejected.

Tip Refer to Features in the Sentinel documentation, for an overview of Sentinel features and how they work.

Registrar Mappers

Mappers overview

The Registrar uses mappers as it processes third-party REGISTER requests.

Tip For an overview of what mappers are and how they work, please see Mappers in the Sentinel documentation.

Mapper execution points

The Registrar searches for mappers at the following mapper execution points:

Mapper Execution Point Role of mappers at this point

DetermineNetworkOperator

Mapping the first-party register request to the network operator lookup key.

ReceivedRegisterRequest

  • Mapping the first-party register request to fields in session state, to store the third-party register request plus the response that is in the body of the first-party register request.

  • Extracting common identities from the third-party register request plus the response (for public and private IDs).

Cdr

Building an audit Call Detail Record that summarises the actions take by the Registrar.
Tip See the enum com.opencloud.sentinel.mapper.RegistrarMappingPoint in the sentinel-sip-registrar-common module.

For a list of all mappers see: Sentinel Registrar Mappers.

Registrar Session Plan

A session plan is the set of possible steps that the registrar may go through when it processes a REGISTER request. There is a session plan for each type of session that Sentinel supports.

Tip For more detail see: What is a Session Plan?

The session plan used by the Registrar is explained here: SIP Session Initiated via third party REGISTER