About the IP Short Message Gateway
The IP Short Message Gateway (IPSMGW) implements transport layer interworking for SMS over IP. It is based on 3GPP TS 24.341, and implements suitable SMS interworking as part of GSMA IR.92 version 9.0
Topics
This document includes the following topics:
Topic | Explains… |
---|---|
how to install the product |
|
the behaviour and configuration of each feature |
|
the behaviour of each mapper |
|
how different phases of MAP are supported |
|
the format and content of CDR files, and the information present in Diameter Ro |
|
how SIP requests are routed to and from the IP-SM-GW |
|
details of Resource Adaptors used by the IP-SM-GW |
|
how data is stored in the Cassandra Database |
|
details of the IFCs that are used for IP-SM-GW routing |
|
license requirements for running IP-SM-GW |
Getting Started
This section explains how to set up a standalone version of Sentinel IPSMGW on a Rhino SDK.
Preparing to Install Sentinel IPSMGW
Before you install Sentinel IPSMGW, you need to download the SDK package, and get other required software.
You can then either:
-
let the built-in installer install both the Rhino SDK and Sentinel IPSMGW, or
-
install and configure Rhino and the JVM manually, then use the installer to install Sentinel IPSMGW into your Rhino
In both cases you need to get a license.
Allowing the installer to install both the Rhino SDK and Sentinel IPSMGW software is recommended for functional testing or experimentation with Sentinel IPSMGW. For production installs and/or load testing it is recommended to manually install and configure Rhino and the JVM.
A Cassandra database is required for an IPSMGW installation.
An OCSS7 Stack is required for an IPSMGW installation.
Finally, if you are planning to install Sentinel IPSMGW on an existing OpenCloud Rhino installation, it makes sense to refer to other OpenCloud product dependencies
Download the Sentinel IPSMGW SDK package
To get the latest Sentinel IPSMGW SDK package go to https://repo.opencloud.com/artifactory/opencloud-sentinel-ipsmgw-3.1.0/opencloud/sentinel-ipsmgw/3.1.0/ipsmgw-sdk/ Choose the version with the highest release number.
The SDK package contains an installer, that can install Sentinel IPSMGW as an out-of-the-box system. It is also an SDK allowing customisation of the product.
You will need OpenCloud-supplied credentials to download the package. |
Get required software
You’ll need the following software to run Sentinel IPSMGW:
Software | Download Link | Documentation Link |
---|---|---|
Java JDK 8, update 172 or later |
http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html |
|
Apache Tomcat 7.0.39 or greater (7.0.x series or 8.5.x series, not 9.x.x series) |
||
Rhino 2.7.0.0 or later - optional - to be used when installing and configuring Rhino manually |
||
Rhino Element Manager 2.7.0.0 or later |
||
Sentinel IP-SM-GW SDK including out of the box installer |
||
Sentinel IP-SM-GW plugin for Rhino Element Manager |
||
Cassandra Database, version 2.1.17 or later version from the 2.1.x series. |
http://cassandra.apache.org/doc/latest/getting_started/index.html |
|
OCSS7, version 2.2.0.0 or later |
https://docs.opencloud.com/ocdoc/books/ocss7/2.2.0/ocss7-home/index.html |
Install and configure Rhino and the JVM
Optionally you can install and configure Rhino and the JVM for use with Sentinel IPSMGW. This is recommended for production deployments, and clustered setups.
Alternatively for Proof of Concept and lab functional testing it is recommended to use the Installer documented in Installing Sentinel IPSMGW Services
Install Rhino
1 |
Start by choosing a location to extract the contents of the Rhino package. We’ll refer to this directory as |
---|---|
2 |
Rhino must be started at least once to generate the necessary configuration files. To start Rhino, in the start-rhino.sh |
3 |
Wait until Rhino is ready. It prints the following message in its log when ready: SLEE successfully started on node(s) [101] |
4 |
Stop Rhino by executing in the stop-rhino.sh --nice |
For more about installing and configuring the Rhino TAS, please see the Rhino Documentation. |
Configure Rhino and the JVM
If you want to install Sentinel IPSMGW in top of an already running Rhino then this step must be performed. If you are letting the installer configure the Rhino SDK for you, this step can be skipped.
The following settings are needed:
Setting | Configuration |
---|---|
Management database size |
For a full Sentinel IPSMGW install, the default Rhino 2.5 management database size is insufficient and should be increased to at least 300MB. To do this, edit <memdb> <jndi-name>ManagementDatabase</jndi-name> <message-id>10003</message-id> <group-name>rhino-db</group-name> <committed-size>300M</committed-size> <stripe-count>1</stripe-count> ... </memdb> |
JVM |
You’ll also need to configure the JVM: In
In
|
Socket permissions |
You will need to add the host address where the installer is running to the mlet configuration file.
<mlets> <mlet enabled="true"> <classpath> <jar-url>$${rhino.dir.base.url}/lib/jmxr-adaptor.jar</jar-url> <security-permission-spec> .... other entries permission java.net.SocketPermission "<IP ADDRESS>", "accept,resolve"; .... other entries </security-permission-spec> </classpath> </mlet> </mlets> |
Start Rhino to load the new configuration
To start Rhino, in the This applies the Rhino and JVM configuration. |
Get a license
To install Sentinel IPSMGW you need a license to run SIS, CGIN, and Sentinel IPSMGW from OpenCloud. In order to obtain a license file, please contact OpenCloud. A full overview of license requirements can be found of this page: License Requirements. |
If you allow the installer to install both Rhino SDK and Sentinel IPSMGW for you, it will prompt you for the location of the license file.
If you prefer to set up Rhino manually, then you need to install the license file prior to installing Sentinel IPSMGW.
To install your license file:
1 |
Make sure Rhino is started and running. |
---|---|
2 |
Go to the |
3 |
In this directory, start the Rhino Console with the |
4 |
In the Rhino Console execute, this command: installlicense [PATH_TO_LICENSE_FILE] ( |
Ports
If using the standard configuration, the following ports need to be open on the IPSMGW TAS host’s firewall.
Port | Purpose |
---|---|
5060 |
SIP traffic |
5061 |
Secure SIP traffic |
8080 |
REM GUI |
1199-1203 |
RMI Access |
If using other configuration the firewall should be configured for those non-standard ports. Other ports may be opened as needed. For example if ssh is used to administer a node, then port 22 would be opened
Cassandra Database
Install and configure a Cassandra Storage with the opencloud_thirdparty_reg
, opencloud_ipsmgw_routing_info
, and opencloud_ipsmgw_registration_ownership
keyspaces.
OCSS7 Stack
Install and configure an OCSS7 stack. Refer to OCSS7 Quick Start.
OpenCloud product dependencies
Sentinel IPSMGW is built on top of other OpenCloud products. The IPSMGW series depends on the following:
Product | Series |
---|---|
Rhino |
2.7.0.x |
REM |
2.7.0.x |
SIP |
2.7.0.x |
CGIN |
2.0.0.x |
SIS |
2.7.0.x |
SIS-EM |
2.6.1.x |
Diameter |
3.1.3.x |
CDR-RA |
2.3.0.x |
HTTP-RA |
2.5.0.x |
DB-Query-RA |
1.4.0.x |
FSM Tool |
1.3.0.x |
CQL-RA |
1.2.0.x |
Installing Sentinel IPSMGW Services
Sentinel IPSMGW is installed through the use of an installer program.
The installer can run in interactive and non-interactive modes - suitable for manual and automated installs respectively. When running in interactive mode it will prompt you for various necessary settings and save them.
The installer will offer to install the Rhino SDK for you, or allow you to specify an existing Rhino installation. Once either a new Rhino SDK install, or an existing installation is selected the installer will install Sentinel IPSMGW into your Rhino or Rhino SDK. |
The installer prepares configuration for a single node Sentinel IPSMGW system, with a single peer for various other network elements such as:
-
Interrogating Call Session Control Function (I-CSCF)
-
Home Location Register (HLR)
-
Cassandra storage for Third Party Registration data
For more advanced configurations, such as clustering or multiple signalling peers, familiarity with the Rhino platform, SIS and Sentinel products is recommended.
To install Sentinel IPSMGW services in interactive mode:
For further information on installation read:
1. Unzip ipsmgw-sdk.zip
To unzip ipsmgw-sdk.zip
:
1 |
Copy the downloaded install zip file to a machine where Rhino and Sentinel IPSMGW will run.
user@machine$ mkdir ~/sentinel-ipsmgw |
||
---|---|---|---|
2 |
Unzip. user@machine$ cp ~/ipsmgw-sdk.zip ~/sentinel-ipsmgw user@machine$ cd ~/sentinel-ipsmgw user@machine$ unzip ipsmgw-sdk.zip |
2. Run the installer
The installer prompts you for various configuration settings, such as the SIP URI for the MRF. You can review and change settings prior to installation so don’t worry if you got something wrong first time. |
The install program is split into several "phases".
These are:
-
initialisation of the environment
-
question and answer (in interactive mode)
-
review settings (in interactive mode)
-
execution of installation
NB: the installer captures full logging from the various tools that it uses, and writes these logs into the ipsmgw-sdk/build/target/log directory.
To run the installer:
1 |
The testuser@machine$ cd ~/sentinel-ipsmgw/ipsmgw-sdk testuser@machine$ ./build/bin/installer The installer first initialises the environment. It typically shows output similar to the following Initialising the SDK ... Retrieving Installer dependencies ... done. |
||
---|---|---|---|
2 |
Question and answer to determine necessary settings The installer will prompt the user for various values. A value inside square brackets, if present, is the default answer for that question. When the user presses the |
||
3 |
Taking the SDK offline The user is prompted whether or not they want to take the SDK offline. You can optionally take the SDK offline by creating a local repository. This will take several minutes depending on connection speed, but will make subsequent retrievals much faster and remove the need for an internet connection. Do you want to take the SDK offline? y/[N] > If the user presses the If the user presses the The user is then presented with progress information related to the downloading of artifacts necessary to take the SDK offline. This process can take more than 30 minutes. |
||
4 |
Basic SDK Questions Your organization's name, e.g. Rocket Communications Inc. sdk.component.vendor [UNSET] > This value will be used for the sdk.component.version [1.0] > This value will be used for the The name of the platform operator, e.g. Rocket. sdk.platform.operator.name [UNSET] > The name of the platform operator for the system. It is used extensively throughout configuration profiles. An Ivy organization field, recommended lower case with no whitespace e.g. "rocket". sdk.ivy.org [UNSET] > This value is used as the sdk.ivy.publish.revision [1.0.0] > This value is used as the base of the |
||
5 |
Rhino details The installer then prompts for details of the Rhino installation used for this installation of IPSMGW. You can either have the installer set up a Rhino SDK for you or point it at an existing Rhino installation, SDK or production. Note: If you want to use an existing Rhino installation it has to be running and a proper license has to be installed when finishing the installation after the configuration. Also make sure that you have adjusted the memory settings and created a tcapsim-gt-table.txt file as detailed in the documentation. Set up a Rhino SDK installation automatically? y/[N] >
If you allow the installer to set up a new Rhino SDK installation, it will prompt for a license file Enter the path to your Rhino license file > /home/testuser/Downloads/opencloud.license It then installs the Rhino SDK and starts it. If you instruct the installer to use an existing Rhino, it will prompt for the path to the Rhino client directory and check if you are using a Rhino SDK or a production cluster. Enter the path to your Rhino client directory > /home/testuser/rhino/client You can either have the installer deploy against Rhino SDK or production. Does the specified client point to a production installation? y/[N] > If you choose Yes, then the installer prompts for details of the cluster nodes and hosts. Enter your Rhino node setup. It has to be formatted like this: {nodeId,nodeId}host,{nodeId}host Examples: {101}localhost {101,102}host1,{103}host2 Node setup [{101}localhost] > {101}hostname1,{102}hostname2 |
||
6 |
Review settings Once the basic SDK configuration questions have been answered, the user is provided the opportunity to review and if happy, accept the settings.
Review settings *************** Basic SDK properties ==================== sdk.component.vendor: Rocket Communications Inc sdk.component.version: 1.0 sdk.platform.operator.name: Rocket sdk.ivy.org: rocket sdk.ivy.publish.revision: 1.0.0 ... edited for brevity Configuration changes written. If the user presses the |
||
7 |
Creation of a deployment module The installer will now create a suitable deployment module. This may take several minutes. |
||
8 |
Home PLMN IDs Questions Home PLMN IDs > The PLMN IDs for the home network. A PLMN ID is entered in the form (MCC,MNC), and multiple PLMN IDs are comma-separated. Example: (001,01),(001,001),(999,99) |
||
9 |
Geo-redundancy configuration Optional configuration for enabling multi-site geo-redundancy support Indicates if IPSMGW should be configured to run across multiple geo-redundant sites. Enable geo-redundancy support y/[N] > If geo-redundancy support is enabled then this additional configuration is required Total number of geo-redundant sites in which IPSMGW will be running (1-16). Total Number of Sites > Unique ID number of this site within the set of geo-redundant sites. Site ID > |
||
10 |
General configuration Details of the IPSMGW environment - hosts, ports, addresses etc The SCCP address of the HLR. This value is used as a template address if 'Use MSISDN as HLR Address' is configured. In this case the configured digits are replaced by the subscriber MSISDN in the outbound HLR address. Examples: type=C7,ri=pcssn,pc=5,ssn=6 or type=C7,ri=gt,digits=0,ssn=6,national=false,nature=INTERNATIONAL,numbering=ISDN,gti=4,tt=0 HLR address [type=C7,ri=pcssn,pc=5,ssn=6] > Within the MAP Proxy and ATM Registration features, controls whether to address the outbound HLR leg using a GT address formed from the subscriber MSISDN, using the configured address as a template. Use MSISDN as HLR Address y/[N] > A Template SCCP address used for routing to SMSC, address will be modified based on the received MSC address. Example: type=C7,ri=gt,digits=0,ssn=8,national=false,nature=INTERNATIONAL,numbering=ISDN,gti=4,tt=0 Template SMSC address [type=C7,ri=gt,digits=0,ssn=8,national=false,nature=INTERNATIONAL,numbering=ISDN,gti=4,tt=0] > The originating SCCP address of the Sentinel IP-SM-GW. Example: type=C7,ri=pcssn,pc=5,ssn=147 Originating Sentinel address [type=C7,ri=pcssn,pc=5,ssn=147] > The international SCCP address of the Sentinel IP-SM-GW. Example: address=653333333,nature=INTERNATIONAL,numberingPlan=ISDN IP-SM-GW Sentinel address [address=653333333,nature=INTERNATIONAL,numberingPlan=ISDN] > The TCAP invoke timeout (in milliseconds). Invoke timeout [5000] > The domain used to compose SIP URIs from the MSISDN. Terminating domain [opencloud.com] > The Address of the Interrogating Call Session Control Function. The hostname part should either be a resolvable name or the IP address of the I-CSCF. Example: sip:127.0.0.1:5052;lr;transport=tcp I-CSCF URI [sip:127.0.0.1:5052;lr;transport=tcp] > The SIP transport used to determine the local SIP URI, which is used as the address of IPSMGW Valid values are: 'udp' or 'tcp'. SIP transport [udp] > The delivery order to use for MT deliveries Valid values are: CS_THEN_PS or PS_THEN_CS or CS_ONLY or PS_ONLY Delivery Order [PS_THEN_CS] > Charging can be enabled separately for MT deliveries over PS and CS, and for MO. Do you want to enable charging over PS for MT deliveries? y/[N] > Do you want to enable charging over CS for MT deliveries? y/[N] > Do you want to enable charging for MO deliveries? y/[N] >
|
||
11 |
Sentinel Registrar Details of the Cassandra database used for Third Party Registration data Please enter a comma separated list of Cassandra contact points in the form "host1,host2" Cassandra Contact Points [localhost] > Please enter the port Cassandra is listening on Cassandra Port [9042] > |
||
12 |
IPSMGW Cassandra IPSMGW uses Cassandra to save routing information that can be shared across nodes and to track registration ownership between sites. Please enter a comma separated list of Cassandra contact points in the form "host1,host2" Cassandra Contact Points [localhost] > Please enter the port Cassandra is listening on Cassandra Port [9042] > |
||
13 |
Sh Cache Microservice RA Configuration that is used by the Sh Cache Microservice RA. The URL for the Sh Cache Microservice. Server URL [http://localhost:8088] > The URL for the Sh Cache Microservice. This is what Sh Cache Microservice requests are sent to. Whether to use a proxy server. Proxy Enabled y/[N] > If yes, the installer will next ask to configure the proxy server. The hostname of the proxy server. Proxy Host [localhost] > Hostname of the proxy server. The port of the proxy server. Proxy Port [3128] > Port of the proxy server. The URL that notifications from Sh Cache Microservice will be sent to. This hostname must be able to be resolved by ShCM hosts. Notification URL [http://localhost:8089] > The notification URL. The local port the RA will listen on for notification requests. This is allowed to differ from the port in 'http.notificationURL', as the local port may not be visible to other nodes depending on the network topology. Notification Port [8089] > The port to listen on for notification requests. Subscription expiry time in seconds. Subscription Expiry Time [3600] > Expiry time for subscriptions to UE Reachability For IP. |
||
14 |
Correlation RA Configuration that is used by the Correlation RA to generate MT Correlation IDs(fake IMSIs). The name of the Correlation ID Pool Pool name [OpenCloud] > In case more than one home PLMN ID was configured in the Home PLM IDs section, the installer will ask what fake MCC and MNC to use in case an IMSI cannot be determined. As this has to be one of the configured home PLMN IDs, if only one home PLMN ID has been configured this will automatically be selected. Fake MCC to use in case the IMSI could not be determined Fake MCC [001] > Fake MNC to use in case the IMSI could not be determined Fake MNC [01] > |
||
15 |
SIP SIS RA Listen Address This specifies the host that you want to receive SIP traffic on. This is the hostname or IP address that you want to receive SIP traffic on. SIP SIS RA Host [localhost] > If installing on a production Rhino with multiple nodes running on the same host, the installer will report that the SIP RA OffsetPort functionality is enabled, with the port offset set to the lowest node ID. The port will default to 5060, modified as described in the configuration. As an example, if nodes 101 and 102 are running on host1, and node 201 is running on host2, the ports used will be 5060-101+101=5060 for node 101, 5060-101+102=5061 for node 102, and 5060-101+201=5160 for node 201. Port offset for SIP SIS RA listen addresses =========================================== Offsetting SIP SIS RA listen ports by nodeId - 101 Otherwise, the port offset functionality will not be enabled and port 5060 will be used by default. Port offset for SIP SIS RA listen addresses =========================================== SIP SIS RA 'port offset' functionality not required, as there are no hosts with multiple nodes running |
||
16 |
OCSS7 Server list for CGIN MAP RA This specifies the OCSS7 server list for the cginmapra entity related to the sccp address. It has to contain the port. This is a comma separated list of hostname or IP address and the port of OCSS7 SGC nodes to connect to. eg localhost:13021,localhost:13022 OCSS7 SGC node Host and Port list [localhost:13021] > |
||
17 |
Diameter Ro and CCA Questions - if any charging options chosen at step 6 This value is placed into the Origin-Host AVP. Host [diameterclient] > The Diameter hostname for Sentinel IP-SM-GW. It is used in the Origin-Host AVP of outgoing diameter messages. This installer allows setting up a simple configuration with a single peer for the OCS. If you need a configuration with multiple peers, you can either do so after the installation finishes by following the Diameter documentation, or editing the following file now: [path-to-config-file]/DiameterConfig.xml Do you want to set up a simple configuration? [Y]/n > If yes, the installer will provide a series of prompts for setting up a basic diameter configuration (where there is a single OCS server); if no, you will need to manually configure diameter peers for the charging system. Peer URI [aaa://diameterserver:3868;transport=tcp] > URI of the online charging server. Diameter peer address [diameterserver] > Diameter address of the online charging server. Realm name [example.com] > Diameter Realm for the online charging system. |
||
18 |
PS Delivery configuration Details for the PS Delivery feature The Timer to decide whether PS Delivery has failed (in milliseconds). Delivery Failure Timer [5000] > The RP-Error codes that will stop fallback if PS_THEN_CS is used. The special value of '-1' will mean no error codes are used. Example: 21,22 Fallback Avoidance Codes [22] > |
||
19 |
PS Delivery Per Node URI This specifies the URI for each node that PSDelivery will set as the From: address in outgoing MESSAGE requests. If installing on a cluster, this question will be repeated for each node specified at the start of the installation process. The SIP Local URI of Rhino node 101. Example: sip:127.0.0.1:5060 Node 101 SIP Local URI [sip:127.0.0.1:5060] > |
||
20 |
CS Delivery configuration Error handling behaviour for the CS Delivery feature The Delivery Error codes that will stop fallback if CS_THEN_PS is used. The special value of '-1' will mean no error codes are used. Example: 0,1 Fallback Avoidance Codes [0] > |
||
21 |
IPSMGW SCCP Whitelist GT Entries This defines a whitelist of incoming SCCP origin addresses that will not be rejected by the IPSMGW SCCP Whitelist feature when triggered by an OpenRequest. Comma separated list of SCCP Whitelist GT Prefixes. The special value of '-' will mean no whitelist is provisioned and all SCCPs will be accepted. Example: 64123,64124 SCCP Whitelist GT Prefix List [-] > |
||
22 |
IPSMGW CDR RA Configuration The configuration properties of the CDR resource adaptor. See Resource Adaptor Configuration for more details. Approximate maximum size in bytes before a new CDR file is started. After a CDR is written, the total file size is compared to MaxSize. If the current file size is larger, it is completed. If MaxSize is 0, no size-based rollover is done. MaxSize [100000000] > Number of records to be written to a CDR file before a new file is started. If MaxCdrs is 0, no record-based rollover is done. MaxCdrs [0] > Number of milliseconds of operation before time-based file rollover. If a CDR file is used for more than MaxInterval seconds without being rolled over due to record- or size-based limits, it is completed anyway. MaxInterval [0] >
|
||
23 |
Review settings Once all questions have been answered, the user is provided the opportunity to review, and if happy, accept the settings.
Review settings *************** Geo-redundancy configuration ============================ Geo-redundancy support enabled?: false General configuration ===================== HLR Address: type=C7,ri=pcssn,pc=5,ssn=6 Use MSISDN as HLR Address: false Template SMSC Address: type=C7,ri=gt,digits=0,ssn=8,national=false,nature=INTERNATIONAL,numbering=ISDN,gti=4,tt=0 Sentinel Originating Address: type=C7,ri=pcssn,pc=5,ssn=147 Sentinel IP-SM-GW Address: address=653333333,nature=INTERNATIONAL,numberingPlan=ISDN HLR Invoke Timeout (ms): 5000 Terminating domain: opencloud.com I-CSCF URI: sip:127.0.0.1:5052;lr;transport=tcp SIP transport: udp Sentinel Registrar ================== Cassandra Contact Points: localhost Cassandra Port: 9042 IPSMGW Cassandra ================ Cassandra Contact Points: localhost Cassandra Port: 9042 Sh Cache Microservice RA ================= Server URL: http://localhost:8088 Proxy Enabled: false Notification URL: http://localhost:8089 Notification Port: 8089 Subscription Expiry Time: 3600 MT Correlation ID ================= Profile name: OpenCloud MCC: 001 MNC: 01 Listen Address for SIP SIS RA ============================= SIP SIS RA Host: localhost Port offset for SIP SIS RA listen addresses =========================================== Not offsetting SIP SIS RA listen port OCSS7 Server list for CGIN MAP RA ============================== OCSS7 SGC node Host and Port list: localhost:13021 Diameter (Ro & CCA) ============================== Host: diameterclient Peer URI: aaa://diameterserver:3868;transport=tcp Peer address: diameterserver Realm name: example.com PS Delivery configuration ========================= PS Delivery Fallback Timer (ms): 5000 RP-Error Fallback Avoidance Codes: [22] PS Delivery Per Node URIs ========================= Node 101 SIP Local URI: sip:127.0.0.1:5060 CS Delivery configuration ========================= Delivery Fallback Avoidance Codes: [0] IPSMGW SCCP Whitelist GT Entries ================================ 64125,64124 IPSMGW CDR RA configuration =========================== MaxSize: 100000000 MaxCdrs: 0 MaxInterval (ms): 600000 Accept these values? [Y]/n > If the user presses the |
||
24 |
Execution phase Now that the installer has gathered all necessary information it provides the user with the option to install the IPSMGW TAS now. Install now? [Y]/n > If the user wants to install at a later time, they can press the If 'Y' is selected the installer proceeds to install Sentinel IPSMGW into Rhino (or Rhino SDK). Publishing deployment module ... done. Deploying; this is going to take a while ... done. Binding; this is going to take a while ... done. Configuring; this is going to take a while ... done. Running post-installation tasks ...done. Installation completed successfully in 11 minutes and 27 seconds. Rhino has been left running to finish applying configuration changes. The installation has now completed successfully. |
A properties file called install.properties is automatically created in the ipsmgw-sdk directory when the interactive installer is run. It stores all the data entered during the install. You can use this file for a new installation using the Non-interactive mode. |
Non-interactive mode
To run the installer in non-interactive mode a properties file is passed to the installer program
testuser@machine$ cd ~/sentinel-ipsmgw/ipsmgw-sdk testuser@machine$ ./build/bin/installer -p my-install.properties
SIS and CGIN
During installation SIS and CGIN versions are extracted into the SDK directory structure. This is so that SIS can be configured as necessary.
The CGIN connectivity pack is extracted into the ipsmgw-sdk/cgin/cgin-connectivity-full-CGIN_VERSION
directory. The SIS is extracted into the ipsmgw-sdk/sis/SIS_VERSION
directory. Here CGIN_VERSION
and SIS_VERSION
are the release versions for each product respectively (e.g. 2.0.0.0 and 2.7.0.0)
The SIS console command is located at ipsmgw-sdk/sis/SIS_VERSION/admin/sis-console
.
Background information
The installer sits on top of the Sentinel IPSMGW SDK infrastructure
The installer works by creation of a 'deployment module' for Sentinel IPSMGW. The module is named "deploy-ipsmgw" and is located in the root of the Sentinel IPSMGW SDK directory.
A deployment module can be created through the use of the sdkadm create-deployment-module command. The values that the user enters (or passes in when using non-interactive mode) are written into the various configuration files in this deployment module.
During an install, the deployment module is first published, then the deployer, binder and configurer are invoked in order to install/bind/configure the application in Rhino.
This means that the the installer is part of the Sentinel IPSMGW SDK, and that there is no technology difference between the SDK and an "off the shelf install". Therefore custom configurations can easily be made through modification of the deployment module, and publishing it, and running the configurer.
Installer log files
The installer captures full logging from the various tools that it uses, and writes these logs into the ipsmgw-sdk/build/target/log directory. This output is more verbose than the user sees when running the installer.
Each time an install is done, a file called install.log is created in this directory. If there is a previous install.log file, that it is moved to install_date.log. The value of "date" is the time of the last write timestamp in the file. i.e. running the installer three times results in three installer log files.
Post-Installation Instructions
Configure the MCC and MNC in SipSentinelConfiguration
There are two required configuration values in SIP Sentinel Configuration which must be configured by hand after installation.
The MCC and MNCs fields are used by Generate MT Correlation Id when a real IMSI could not be retrieved from the HLR.
These can be set through either REM or the rhino-console.
Create init.d scripts
There are two init.d
scripts for Ubuntu Linux which make starting and stopping Rhino and REM easier (linked below):
Note: These are illustrative and useful for Proof of concept rather than production environments.
To set these up:
1 |
Copy the script to the host server’s sudo cp rhino /etc/init.d |
---|---|
2 |
Make the script executable: |
3 |
Refresh, with the sudo update-rc.d rhino defaults 99 |
Init.d Sample Scripts for IPSMGW
These sample scripts are illustrative init.d scripts for Rhino and REM |
For production installations use production Rhino’s own init.d scripts rather than these.
Sample Rhino script
#!/bin/bash # # Manage the Rhino SLEE. # Put this file in /etc/init.d and symlink that in /etc/rc?.d RHINO_HOME=/home/ubuntu/ipsmgw-sdk/rhino-sdk/RhinoSDK RHINO_USER=ubuntu case "$1" in start) # This command will fail nicely if that file is not there, so # checking for that file's existence is not necessary. echo "Starting the Rhino SLEE" sudo su - ${RHINO_USER} -c ${RHINO_HOME}/start-rhino.sh > /dev/null 2>&1 & # logs will be in ${RHINO_HOME}/work/log ;; stop) echo "Stopping the Rhino SLEE" [ -d ${RHINO_HOME} ] && [ -x ${RHINO_HOME}/stop-rhino.sh ] \ && ${RHINO_HOME}/stop-rhino.sh --nice ;; *) echo "Usage: $0 { start | stop }" exit 1 ;; esac exit 0
Sample REM script
#!/bin/sh # # Rhino Element Manager start/stop script. # # # Location of the Rhino Element Manager REM_HOME=/home/ubuntu/ipsmgw-sdk/rhino-sdk/RhinoSDK/apache-tomcat-* RHINO_USER=ubuntu usage() { echo "Usage: $0 {start|stop}" exit 1 } # # Main # # Parameter check [ $# -gt 0 ] || usage case "$1" in start) # Start REM sudo su - "$RHINO_USER" -c "$REM_HOME/bin/catalina.sh start" echo "REM Starting" ;; stop) # Stop REM sudo su - "$RHINO_USER" -c "$REM_HOME/bin/catalina.sh stop" echo "REM Stopping" ;; *) usage exit 2 ;; esac exit 0
Installing the IPSMGW Element Manager Module
The IPSMGW Element Manager module is distributed as a Rhino Element Manager (REM) plugin.
The IPSMGW Element Manager module should be installed if the REM instance is only used to provision Sentinel-IPSMGW. If REM will be used to provision both Sentinel-VoLTE and Sentinel-IPSMGW installations then only the Sentinel VoLTE provisioning module should be installed. The Sentinel VoLTE provisioning module is capable of provisioning both Sentinel-IPSMGW and Sentinel-VoLTE installations. See Installing the Sentinel VoLTE Provisioning Module. |
It requires a standalone distribution of REM 1.5.0.4 or later. REM can be installed with Jetty or Apache Tomcat. For IPSMGW, the Apache Tomcat method is required.
You’ll need these files to install the IPSMGW Element Manager module:
-
apache-tomcat-<version>.zip
-
rhino-element-manager-<version>.zip
-
ipsmgw-element-manager-<version>.em.jar
Below are the procedures to:
Set up Tomcat
To set up Apache Tomcat for the IPSMGW Element Manager module:
1 |
Follow the instructions for running REM on Apache Tomcat in the REM Guide. |
---|---|
2 |
Create the cd apache-tomcat-<version> mkdir -p rem_home/plugins |
Install the REM plugin
To install the REM plugin for the IPSMGW Element Manager Module:
1 |
Copy cd apache-tomcat-<version> cp /full/path/to/ipsmgw-element-manager-<version>.em.jar rem_home/plugins/ |
---|
Customize plugin logging
1 |
Unzip cd apache-tomcat-<version> mkdir rem-tmp cd rem-tmp unzip ../webapps/rem.war WEB-INF/classes/log4j.properties |
---|---|
2 |
Edit log4j.rootLogger=INFO, FILE, CONSOLE log4j.appender.CONSOLE=org.apache.log4j.ConsoleAppender log4j.appender.CONSOLE.layout=org.apache.log4j.PatternLayout log4j.appender.CONSOLE.layout.ConversionPattern=%d{ABSOLUTE} %-5p <%t> [%c] %m%n log4j.appender.FILE=org.apache.log4j.FileAppender log4j.appender.FILE.File=${rem.home}/rem.log log4j.appender.FILE.layout=org.apache.log4j.PatternLayout log4j.appender.FILE.layout.ConversionPattern=%d{yyyy-MM-dd HH:mm:ss,SSS} %-5p <%t> [%c] %m%n log4j.logger.rem=INFO log4j.logger.openjpa=INFO log4j.logger.org.apache.wink=INFO log4j.logger.sentinel.audit=INFO, AUDIT log4j.additivity.sentinel.audit=false log4j.appender.AUDIT=org.apache.log4j.FileAppender log4j.appender.AUDIT.File=${rem.home}/sentinel-audit.log log4j.appender.AUDIT.layout=org.apache.log4j.PatternLayout log4j.appender.AUDIT.layout.ConversionPattern="%d{yyyy-MM-dd HH:mm:ss,SSS}", "%c{1}", %m%n |
3 |
Replace zip ../webapps/rem.war WEB-INF/classes/log4j.properties |
4 |
Remove temporary files: cd .. rm -rf rem-tmp |
Import Rhino trust certificate
This can also be done using the REM web UI.
1 |
Import a Rhino Trust Certificate into REM: "${JAVA_HOME}/bin/keytool" -importcert -file ${RHINO_HOME}/rhino-trust.cert -keystore "${TOMCAT_HOME}/rem_home/rhino-ems.ks" -storepass changeit -noprompt |
---|
Security considerations
Below are recommendations for securely running the IPSMGW Element Manager Module.
Use https
Be aware that the IPSMGW Element Manager machine API uses HTTP BASIC authentication. This passes the username and password with every request.
To prevent your credentials going over the network unencrypted, run REM over https.
Set up SSL
See the Tomcat 7 - SSL How-To docs for help setting up SSL in Apache Tomcat 7.
Virtualized Deployment Requirements
Sentinel IPSMGW is supported in a virtualized environment, details presented here provide a guide to the scope of that support and how Sentinel IPSMGW should be setup in that environment.
VMWare Supported
VMWare vSphere ESXi 5.1 and 6 is supported and certified. vCenter is not a mandatory requirement. |
Operating System Support
Please refer to the Platforms section of the Rhino Compatibility Guide for supported operating systems. |
Dedicated Storage Array Required
Sentinel IPSMGW does not require dedicated storage. CDR files and Rhino logs should be partitioned separately and managed to avoid failure or data loss due to space utilization. |
CPU Contention Supported
CPU Contention is supported, however %ready numbers should be kept below 5% to avoid significant impact on overall application performance. It is strongly recommended that VMs are bound to physical CPU sockets to ensure predictable latency. |
Fault Tolerance
A rhino cluster provides support for both high availability and fault tolerance internally. Sentinel IPSMGW does not make use of the Rhino replication but does use the high availability systems. The cluster as a whole can tolerate failure of individual nodes with no support from the virtual machine. Live replication of virtual machines (FT Model) will interfere with Rhino’s internal clustering mechanisms. |
VMWare vSphere High Availability
Sentinel IPSMGW provides is own HA clustering based upon the Rhino SLEE Architecture. |
Test Lab Minimum Virtual Host Requirements
1 vCPU, 8Gb RAM, 30Gb HD, 0 IOPS (Disk I/O is not normally a significant requirement as it’s not used except for logging and installation/configuration changes. Under normal operation a rhino node produces very little logging, but can use > 100Mb/s during severe error conditions under load). |
Production Minimum Virtual Host Requirements
1 Rhino node per VM, 1 CPU (bound) @2.4+Ghz, 12Gb java heap, 30Gb HD, 0 IOPS. A quorum node is much lighter weight, and would require a vm with 1 vcpu, 512Mb ram, 0 IOPS. |
Scalability
Linear to 2.4Ghz, No scaling improvement over 2.4Ghz. (At Maximum load @ 2.4GHz, we reach saturation of Java CMS collector). |
Virtual host resource changes while running
Sentinel IPSMGW does not support host resource changes while running. |
Features
This page presents summaries and links to more detailed descriptions of Sentinel IP Short Message Gateway (IPSMGW) features.
Common features
These are common features that are used in several flows
Feature | What it does |
---|---|
instructs the Sentinel core to accept the incoming dialog. |
|
is responsible for building a Call Detail Record that reflects the actions taken whilst processing a session. |
|
records various information from incoming messages needed by the AVP CDR feature. |
|
uses information from the incoming TCAP message request or Sh Push Notification Result to determine the MSISDN and set it in session state |
|
uses information from the incoming TCAP message request or Sh Push Notification Result and sets the plan ID in the Sentinel selection key in Session State field. The plan ID affects which features will run for the call on the current AS instance. |
|
sets the session state field |
|
selects the behaviour of the IPSMGW when a SIP Message request is received. |
|
analyses the contents of an incoming Tcap Message to determine if it contains a |
|
analyses the contents of an incoming Tcap Message to determine if it contains SRIForSM result SUCCESS or FAILURE (AbsentSubscriber). |
|
sets the network operator element of the Sentinel selection key |
|
defines immediate event charging of MO- and MT-FSMs delivered over the PS and CS networks for Sentinel as an IPSMGW. |
|
clears all pending requests and ends all legs. |
|
determines Mobile Country Code (MCC), Mobile Network Code (MNC), and ISO Country Code values for the subscriber. |
|
uses an MSISDN to fetch the IMSI from the HLR via a SendRoutingInfoForSMRequest |
|
proxies MAP messages between two network elements, typically a Serving MSC (SMSC) and an MSC. |
|
modifies outbound messages sent between two network elements, typically a Serving MSC (SMSC) and an MSC. |
|
uses an IMSI to send a ReadyForSM to the HLR and handles the response |
|
instructs the Sentinel core to reject the incoming dialog. |
|
rejects OpenRequests from SCCP addresses it does not recognize based on a provisioned whitelist. |
Mobile Originated Features
These features relate to the SMS Submission path from the UE to the network.
Feature | What it does |
---|---|
submits an SMS Over IP request to the SMSC. |
|
updates the Orig-Address of outbound MAP MT-ForwardSM requests to allow CAP charging of the session. |
|
sends an SMS Submit Report to an SMS over IP capable UE |
Mobile Terminated Features
These features relate to the SMS Delivery path from the network to the UE.
Feature | What it does |
---|---|
modifies the MSC address in Send Routing Info For SM responses to be the configured address of the IPSMGW. This ensures that subsequent MAP MT Forward Short Message requests are sent to the IPSMGW. |
|
stores SMS routing information in Cassandra. The stored data includes additional correlation information. |
|
retrieves Circuit Switched routing information from the Cassandra Database and stores it into session state. |
|
reads Third Party Registration information stored in the Cassandra Database, and writes it into session state. |
|
delivers an SMS encapsulated in SIP (SMS Over IP) to the UE |
|
delivers a Short Message towards the MSC or SGSN, performing TCAP application context negotiation as necessary |
|
generates a correlation IMSI when responding to a SRI request. It uses the Correlation Resource Adaptor to allocate an IMSI based on the MCC and MNC. |
|
increments (or creates) a row in the Cassandra cluster for the current MSISDN, to be used as the RP Message Reference, writing the value into session state. |
|
links incoming SIP delivery reports with the sentinel session that the delivery report is responding to. |
|
generates a response to a SRI for SM request when the system is configured to attempt PS delivery only. |
Preserve Call Id Over B2BUA
The SIP B2BUA feature can be configured to preserve the Call-ID
header across both legs of a B2BUA’d session. Certain MT flows require the correlation of an incoming request with an existing IP-SM-GW session. This is achieved using the In-Reply-To
header of the incoming request. Depending on network configuration this may require the preservation of the Call-ID
header when B2BUA’ing the MESSAGE request onwards. By default and in typical deployments, this behavior is not configured. It should only be configured if required. For more information on this configuration option read the B2BUA Feature Configuration documentation.
Short Message Memory Available Features
These features relate to the Short Message Memory Available Submission path from the UE to the network. This occurs when the UE indicates that it has memory available to receive short messages, having previously indicated that it did not have available memory.
Feature | What it does |
---|---|
extracts the MSISDN from a SMMA message, then sends an RP-ACK to the SMMA request |
Registrar features
These features relate to Third Party Registration
Feature | What it does |
---|---|
sets a session state field based on the presence of the “+g.3gpp.smsip” parameter in first party SIP Register request Contact headers and the subscriber MSISDN session state field. |
|
sends a MAP AnyTimeModification request to HLR to set the IP-SM-GW address and set active flag to true when a user registers. |
|
records registration requests in Cassandra to keep track of which site a user last registered at. |
USSI features
These features relate to processing USSI requests.
Feature | What it does |
---|---|
analyses an incoming INVITE request to determine if it is a USSI request. |
|
handles the SIP side of the USSI conversation. |
|
converts USSD text to/from encoded forms |
|
generates and sends a USSD request to an HLR, and handles the result |
Common Features
These are common features that are used in several flows
Feature | What it does |
---|---|
instructs the Sentinel core to accept the incoming dialog. |
|
is responsible for building a Call Detail Record that reflects the actions taken whilst processing a session. |
|
records various information from incoming messages needed by the AVP CDR feature. |
|
uses information from the incoming TCAP message request or Sh Push Notification Result to determine the MSISDN and set it in session state |
|
uses information from the incoming TCAP message request or Sh Push Notification Result and sets the plan ID in the Sentinel selection key in Session State field. The plan ID affects which features will run for the call on the current AS instance. |
|
sets the session state field |
|
selects the behaviour of the IPSMGW when a SIP Message request is received. |
|
analyses the contents of an incoming Tcap Message to determine if it contains a |
|
analyses the contents of an incoming Tcap Message to determine if it contains SRIForSM result SUCCESS or FAILURE (AbsentSubscriber). |
|
sets the network operator element of the Sentinel selection key |
|
defines immediate event charging of MO- and MT-FSMs delivered over the PS and CS networks for Sentinel as an IPSMGW. |
|
clears all pending requests and ends all legs. |
|
determines Mobile Country Code (MCC), Mobile Network Code (MNC), and ISO Country Code values for the subscriber. |
|
uses an MSISDN to fetch the IMSI from the HLR via a SendRoutingInfoForSMRequest |
|
proxies MAP messages between two network elements, typically a Serving MSC (SMSC) and an MSC. |
|
modifies outbound messages sent between two network elements, typically a Serving MSC (SMSC) and an MSC. |
|
uses an IMSI to send a ReadyForSM to the HLR and handles the response |
|
instructs the Sentinel core to reject the incoming dialog. |
|
rejects OpenRequests from SCCP addresses it does not recognize based on a provisioned whitelist. |
AVP CDR
This feature is responsible for building a Call Detail Record that reflects the actions taken whilst processing a session.
It runs once when a session is ending and creates a CDR based on information gathered from session state, and then writes it out using the cdr-ra
.
By default, Sentinel runs featurescript PostEndSession { run IpsmgwAvpCdr } |
Feature cheat sheet
Feature Name | Network Operator Data | Used in PlanId(s) | Stateful or Stateless | POJO Feature or SBB Feature |
---|---|---|---|---|
IpsmgwAvpCdr |
No |
N/A |
Stateless |
POJO |
Session state inputs and outputs
Inputs
If any of these fields are unset the feature will skip writing them to the CDR file.
This feature uses the same session state fields as the Sentinel SIP AVP CDR feature. This page will only discuss the additions to the fields described there.
Name | Type | Description | Where set |
---|---|---|---|
SubmitReportType |
Enumerated |
The submit report type for the |
|
MSISDN |
String |
The MSISDN of a subscriber |
Fetch Routing Info Cassandra feature, MO Submission feature, SMMA Response feature, Store Routing Info Cassandra feature |
IMSI |
String |
The IMSI of a subscriber |
|
MTCorrelatedId |
String |
The MT correlated ID |
Fetch Routing Info Cassandra feature, Generate MT Correlation Id feature |
PSDeliveryStatus |
Enumerated |
The PS delivery status; one of |
|
CSDeliveryStatus |
Enumerated |
The CS delivery status; one of |
|
Impu |
String |
The IMPU of a subscriber |
|
OrigSccpAddress |
String |
The origination SCCP address of a call |
|
DestSccpAddress |
String |
The destination SCCP address of a call |
Functionality
This features uses the information from the session state fields mentioned above and constructs a protobuf message out of it for output. See AVP CDR Format for the format of these messages.
Also see Charging Information for general information about the contents of CDRs and CCRs.
This feature only supports writing binary CDRs. If the cdr-ra is configured to write string CDRs the feature will fail to execute. |
Accept Dialog
This feature instructs the Sentinel core to accept the incoming dialog.
Feature cheat sheet
Feature Name | Network Operator Data | Used in PlanId(s) | Stateful or Stateless | POJO Feature or SBB Feature |
---|---|---|---|---|
IPSMGWAcceptDialog |
No |
MTFSM_PS_CS,MTFSM_CS_PS,MTFSM_PS,MTFSM_CS |
Stateless |
POJO |
Configuration
The feature uses the Shared Configuration Profile
. The following attributes are used:
Attributes | Type | Meaning |
---|---|---|
UseGtAsCallingParty |
Boolean |
When accepting an OpenRequest, the SCCP responder address in the OpenAccept will, by default, be set to the value of the SCCP called party in the OpenRequest. If This is useful when the inbound sccp-called-party has been modified by a network element to use PCSSN routing, but GT routing is required for establishing the TCAP dialog. |
CDR Info
This feature records various information from incoming messages needed by the AVP CDR feature.
Feature cheat sheet
Feature Name | Network Operator Data | Used in PlanId(s) | Stateful or Stateless | POJO Feature or SBB Feature |
---|---|---|---|---|
CDRInfo |
No |
N/A |
Stateless |
POJO |
Configuration
The feature has no configuration.
Outputs
Name | Type | Description |
---|---|---|
Impu |
String |
The IMPU determined from an incoming SIP response on an MTFSM plan ID |
OrigSccpAddress |
String |
The origination SCCP address taken from an incoming dialog TCAP message |
DestSccpAddress |
String |
The destination SCCP address taken from an incoming dialog TCAP message |
Behaviour
The feature examines incoming SIP and TCAP messages and extracts information from them. This information is saved in session state fields to make it available to the AVP CDR feature that runs at the end of a session.
Determine Is SMS Over IP
This feature selects the behaviour of the IPSMGW when a SIP Message request is received.
Feature cheat sheet
Feature Name | Network Operator Data | Used in PlanId(s) | Stateful or Stateless | POJO Feature or SBB Feature |
---|---|---|---|---|
IPSMGWDetermineIsSMSOverIP |
No |
Any |
Stateless |
POJO |
Statistics
IPSMGWDetermineIsSMSOverIP statistics are tracked by the sentinel.ipsmgw SBB and can be found under the following parameter set in REM:
SLEE-Usage → sentinel.ipsmgw service → sentinel.ipsmgw SBB → feature → IPSMGWDetermineIsSMSOverIP
or with rhino-stats:
"SLEE-Usage.Services.ServiceID[name=sentinel.ipsmgw,vendor=OpenCloud,version=3.1.0].SbbID[name=sentinel.ipsmgw,vendor=OpenCloud,version=3.1.0].feature.IPSMGWDetermineIsSMSOverIP"
Name | Description |
---|---|
IsSMSOverIP |
Incremented when a SIP MESSAGE’s Content-Type is |
SentSuccess |
Incremented when a 'success' final response is sent (e.g. 202) |
SentError |
Incremented when a 'error' final response is sent (e.g. 403) |
SessionIsMOFSM |
Incremented when MESSAGE’s RP-DATA direction is from MobileStation to Network |
Behaviour
If the SIP Message Request body does not include an SMS, the default product configuration has the IP-SM-GW act as a Routing B2BUA, thereby sending the SIP Message request towards the S-CSCF.
The Content-Type
header is checked to see if it is application/vnd.3gpp.sms
, and if so this indicates that the request is SMS over IP related. The session state field IsSMSOverIP
set to true. If the Content-Type header does not match the feature finishes execution.
Next the body of the SIP Message Request is parsed as an RP Message. If parsing is unsuccessful the feature sends a 403 response, increments the SentError
statistic and finishes execution.
Assuming that parsing is successful, the feature then checks the RP Message Type Indicator for directionality of MS to Network
. If the direction is Network to MS
it is a message type that the IP-SM-GW does not process, so the feature finishes execution and the IP-SM-GW will act as a Routing B2BUA.
Assuming the direction is MS to Network
, the following occurs:
-
if the RP Message Type indicates RP-DATA, the feature sets the Sentinel Selection Key’s PlanID field to the value "MOFSM". This corresponds to the MO Submission Flows, and Mobile Originated Features.
-
if the RP Message Type indicates RP-SMMA, the feature sets the Sentinel Selection Key’s PlanID field to the value "SMMA". This corresponds to the Short Message Memory Available Flows.
-
if the RP Message Type indicates RP-ACK, or RP-ERROR, the feature sets the Sentinel Selection Key’s PlanID field to the value "MTFSM_DR". This corresponds to the Delivery Report portion of the MT Delivery Flows.
Determine MSISDN
This feature uses information from the incoming TCAP message request or Sh Push Notification Result to determine the MSISDN and set it in session state
Feature cheat sheet
Feature Name | Network Operator Data | Used in PlanId(s) | Stateful or Stateless | POJO Feature or SBB Feature |
---|---|---|---|---|
IPSMGWDetermineMSISDN |
No |
SRI4SM and Sh_PNR |
Stateless |
POJO |
Statistics
IPSMGWDetermineSessionPlan statistics are tracked by the sentinel.ipsmgw SBB and can be found under the following parameter set in REM:
SLEE-Usage → sentinel.ipsmgw service → sentinel.ipsmgw SBB → feature → IPSMGWDetermineMSISDN
or with rhino-stats:
"SLEE-Usage.Services.ServiceID[name=sentinel.ipsmgw,vendor=OpenCloud,version=3.1.0].SbbID[name=sentinel.ipsmgw,vendor=OpenCloud,version=3.1.0].feature.IPSMGWDetermineMSISDN"
Name |
Description |
FailedToDetermineMSISDN |
Incremented when the MSISDN can’t be determined |
IgnoringTrigger |
Incremented when the trigger is not TCAP OpenRequest or Sh UEReahabilityForIP PNR |
Determine Network Operator
Description
Feature name |
IPSMGWDetermineNetworkOperator |
---|---|
Applicable contexts |
IPSMGW service |
Prerequisite features |
None |
The IPSMGW Determine Network Operator Feature sets the network operator element of the Sentinel selection key for use in the selection of:
-
feature execution scripts
-
mappers
-
address lists.
This feature is needed for multi-tenancy scenarios. This feature is intended to be used in the direct access case.
The feature will set the Network Operator element of the Sentinel selection key, based on the value returned by the DetermineNetworkOperator function below.
Session state inputs and outputs
Error scenarios
Scenario | Handling |
---|---|
Sessionstate SentinelSelectionKey is null |
Report featureCannotStart |
Trigger is null |
Report featureCannotStart |
Trigger event not a TCAPMessage or Push notification request |
Report featureCannotStart |
TCAP open request is null |
Report featureCannotStart |
DestinationAddress in DialogOpenRequestEvent is null |
Report featureCannotStart |
Could not match DestinationAddress in IPSMGWDetermineNetworkOperatorGlobalTitleAddress |
Increment CouldNotDetermineNetworkOperator |
Feature responses
Response | Reason |
---|---|
featureCannotStart |
Trigger event must be DialogOpenRequestEvent or PushUEReachabilityForIPResult, SessionState SentinelSelectionKey is not set, unsupported trigger, destination SCCP address not present in DialogOpenRequestEvent or destination SCCP GT address does not match and no default available |
featureHasFinished |
feature has finished |
Behaviour
The following logic is used for determining the Network Operator
-
If the trigger is a push notification request that is not associated with a subscription by this service, then the default network operator is used
-
If the destinationSccpAddress.GT is not available, then the default network operator is used
-
If the destinationSccpAddress.GT is available but not found in the network operator selection table, then the default network operator is used
-
If the destinationSccpAddress.GT is found in the network operator selection table, then the network operator value from the matched selection table record is used.
The use of the destinationSccpAddress GT information is dependent on the subscriber’s HPLMN network configuration. It is possible that some networks may not pass the GT information set in the subscriber’s o-CSI or t-CSI.
Here is an example of SCCP address routing which includes the GT information:
application context: CAP-v2-gsmSSF-to-gsmSCF-AC CAP OpenService Type: request/indication bitmask=0x1 CapOpenArg: { applicationContext: 0 4 0 0 1 0 50 1 nextBlockOpCode: not present originatingAddress: { P=C7, NI=0, RI=PCSSN, GTI=0, pc=5, SSN=146 } destinationAddress: { P=C7, NI=0, RI=PCSSN, GTI=4, SSN=146, TT=0, NP=1 (isdn), ES=2 (even), NAI=4 (international num), DIG=420603059300 } gprsOriginatingReference: not present gprsDestinationReference: not present user information length: not present }
For subscribers who are configured for intra-PLMN only, it is possible that the CSI may contain a gsmSCP address containing only PC/SSN. In this case, the feature cannot operate, as no GT information will be available.
Configuration
Network Operator Destination Global Title SCCP Address Lists Selection Table:
Parameter | Type | Example Values |
---|---|---|
Address |
GT Address |
642100000012 |
NetworkOperator |
String |
MVNO1 |
Example table:
Address | NetworkOperator |
---|---|
642100000001 |
OpenCloud |
642100000011 |
OpenNet |
642100000022 |
CloudNet |
The default network operator is stored in the Sentinel configuration table.
Configuration profile naming
Configuration Profile Table Name | Description | Profile Naming |
---|---|---|
${PLATFORMOPERATOR}_IPSMGWDetermineNetworkOperator_AddressListConfigurationTable |
Address list configuration |
${SELECTIONKEY}:IPSMGWDetermineNetworkOperator:GlobalTitleAddress |
${PLATFORMOPERATOR}_IPSMGWDetermineNetworkOperator_AddressListEntryTable |
Feature-specific Address List entry table |
${SELECTIONKEY}:IPSMGWDetermineNetworkOperator:GlobalTitleAddress:${ADDRESS} |
SentinelConfigurationTable |
Sentinel configuration table (contains DefaultNetworkOperator) |
SentinelConfiguration |
Provisioning interfaces
The feature is provisioned using the Sentinel Features REST API.
Determine SRIForSM Result Failure
This feature analyses the contents of an incoming Tcap Message to determine if it contains SRIForSM result SUCCESS or FAILURE (AbsentSubscriber).
Feature cheat sheet
Feature Name | Network Operator Data | Used in PlanId(s) | Stateful or Stateless | POJO Feature or SBB Feature |
---|---|---|---|---|
DetermineSRIForSMFailureResult |
No |
N/A |
Stateless |
POJO |
Session Input variables
The feature reads the following fields in Session State
Session State variable name | Variable type | Comments |
---|---|---|
MTFSMDeliveryOrder |
com.opencloud.sentinel.ipsmgw.shared.config.profile.DeliveryOrder |
In the absentSubscriber case, If CS_ONLY, will set LookupIMSRegistration to false |
Session Output variables
The feature sets the following fields in Session State
Session State variable name | Variable type | Comments |
---|---|---|
LookUpIMSRegistration |
Boolean |
|
SRI4SMResult |
enum |
Indicates if the SendRoutingInfoForSM request has succeeded. Allowed values are |
SRI4SMError |
TcapError |
The TcapError received in response to the SendRoutingInfoForSMRequest |
Behaviour
The feature checks if the trigger message is a TCAP Message, if it is then it analyses the components to determine if the Tcap Message contains a SRIForSM response and sets the following session state fields:
-
SRI4SMResult
SUCCESS
orFAILURE
depending on whether a TCOperationResult or TCError -
LookupIMSRegistration
if a TCErrorAbsentSubscriber
was received.
Both are used subsequently in feature scripts to control behaviour, LookupIMSRegistration
is used to indicate whether subscriber data should be read from Cassandra (IMS Registration). If the subscriber is IMS registered or the SRIForSM result indicated success then delivery will be attempted.
SRI4SM_SipThirdPartyAccess_PartyResponse:
FeatureScriptSrc: featurescript SipThirdPartyAccessPartyResponse {
run IPSMGWMapProxy
run DetermineSRIForSMFailureResult
if session.LookupIMSRegistration {
run IPSMGWRegistrationLookupFromCassandra
}
if session.isSMSOverIPRegistered or session.SRI4SMResult.SUCCESS {
run IPSMGWModifySRILeg
run IPSMGWGenerateMTCorrelationId
run IPSMGWStoreRoutingInfoCassandra mode "store"
run IPSMGWAdjustRoutingInfoResponse
}
}
Determine Session Plan
This feature uses information from the incoming TCAP message request or Sh Push Notification Result and sets the plan ID in the Sentinel selection key in Session State field. The plan ID affects which features will run for the call on the current AS instance.
Feature cheat sheet
Feature Name | Network Operator Data | Used in PlanId(s) | Stateful or Stateless | POJO Feature or SBB Feature |
---|---|---|---|---|
IPSMGWDetermineSessionPlan |
No |
N/A |
Stateless |
POJO |
Session Input variables
The feature reads the following fields in Session State
Session State variable name | Variable type | Comments |
---|---|---|
SentinelSelectionKey |
com.opencloud.sentinel.common.SentinelSelectionKey |
selection key (for example, |
MTFSMDeliveryOrder |
com.opencloud.sentinel.ipsmgw.shared.config.profile.DeliveryOrder |
If already set, will not be updated |
Session Output variables
The feature sets the following fields in Session State
Session State variable name | Variable type | Comments |
---|---|---|
MTFSMDeliveryOrder |
com.opencloud.sentinel.ipsmgw.shared.config.profile.DeliveryOrder |
DeliveryOrder retrieved from configuration |
Statistics
IPSMGWDetermineSessionPlan statistics are tracked by the sentinel.ipsmgw SBB and can be found under the following parameter set in REM:
SLEE-Usage → sentinel.ipsmgw service → sentinel.ipsmgw SBB → feature → IPSMGWDetermineSessionPlan
or with rhino-stats:
"SLEE-Usage.Services.ServiceID[name=sentinel.ipsmgw,vendor=OpenCloud,version=3.1.0].SbbID[name=sentinel.ipsmgw,vendor=OpenCloud,version=3.1.0].feature.IPSMGWDetermineSessionPlan"
Name |
Description |
ReceivedSRI4SM |
Incremented when OpenRequest is shortMsgGatewayContext |
ReceivedMOFSM |
Incremented when OpenRequest is shortMsgMO_RelayContext |
ReceivedMTFSM |
Incremented when OpenRequest is shortMsgMT_RelayContext |
ReceivedPNR |
Incremented when the trigger is a Sh UEIPReachability PNR |
ReceivedUnknownACN |
Incremented when OpenRequest is none of the context above |
ReceivedUnknownTrigger |
Incremented when the trigger is not TCAP OpenRequest |
Behaviour
The feature checks if the trigger message is a TCAP OpenRequest message or a Sh UEReahabilityForIP Push Notification Result. If it is a TCAP OpenRequest message, then the PlanId
selection key field is set to SRI4SM
, MOFSM
, MTFSM_<DeliveryOrder>
[1] or UnknownACN
. The configured DeliveryOrder
is set in the MTFSMDeliveryOrder session state field unless MTFSMDeliveryOrder was already set. If it is a Sh Push Notification Result, then the PlanId
selection key field is set to Sh_PNR
. Otherwise the feature does not set the PlanId
field of the SentinelSelectionKey session state field.
Plan ID selection circumstances
Session Trigger | Resulting PlanId |
---|---|
MAP shortMsgGatewayContext_v1_ac |
SRI4SM |
MAP shortMsgMO_RelayContext_v1_ac |
MOFSM |
MAP shortMsgMT_RelayContext_v1_ac |
One of: |
Sh UEReachabilityForIP Push Notification Result |
Sh_PNR |
Determine Session Type
This feature sets the session state field SessionType
to map
or Sh_PNR
.
Feature cheat sheet
Feature Name | Network Operator Data | Used in PlanId(s) | Stateful or Stateless | POJO Feature or SBB Feature |
---|---|---|---|---|
IPSMGWDetermineSessionType |
No |
N/A |
Stateless |
POJO |
Statistics
IPSMGWDetermineSessionType statistics are tracked by the sentinel.ipsmgw SBB and can be found under the following parameter set in REM:
SLEE-Usage → sentinel.ipsmgw service → sentinel.ipsmgw SBB → feature → IPSMGWDetermineSessionType
or with rhino-stats:
"SLEE-Usage.Services.ServiceID[name=sentinel.ipsmgw,vendor=OpenCloud,version=3.1.0].SbbID[name=sentinel.ipsmgw,vendor=OpenCloud,version=3.1.0].feature.IPSMGWDetermineSessionType"
Name | Description |
---|---|
ReceivedTcap |
Incremented when a TCAP message is received |
ReceivedPnr |
Incremented when a Sh UEReachabilityForIP PNR is received |
ReceivedUnknownTrigger |
Incremented when message received is not a TCAP message or Sh PNR |
Behaviour
The feature checks if the trigger message is a TCAP message or a Sh UEReahabilityForIP Push Notification Request. If it is a TCAP message, then the session state field SessionType
is set to map
. If it is a Push Notification Request, then the session state field PlanId
is set to Sh_PNR
. Otherwise the feature leaves the SessionType
session field state unset.
Determine Tcap Message Components
This feature analyses the contents of an incoming Tcap Message to determine if it contains a SINGLE_COMPONENT_TYPE
or MULTIPLE_COMPONENT_TYPES
.
Feature cheat sheet
Feature Name | Network Operator Data | Used in PlanId(s) | Stateful or Stateless | POJO Feature or SBB Feature |
---|---|---|---|---|
DetermineTcapMessageComponents |
No |
N/A |
Stateless |
POJO |
Session Output variables
The feature sets the following fields in Session State
Session State variable name | Variable type | Comments |
---|---|---|
TcapMessageComponents |
Enum |
possible values, |
Behaviour
The feature checks if the trigger message is a TCAP Message,if it is then it analyses the components to determine if the Tcap Message contains either a SINGLE_COMPONENT_TYPE
or MULTIPLE_COMPONENT_TYPES
(TCOperationResult and TCOperationInvoke) and sets a session state field. The value of the session state field can then be used subsequently in feature scripts to select which features to run. The following excerpt demonstrates how the feature and session state field can be used in feature scripts.
SRI4SM_SipThirdPartyAccess_PartyRequest:
FeatureScriptSrc: featurescript SipThirdPartyAccessPartyRequest {
run IPSMGWMapProxy
run DetermineTcapMessageComponents
if session.TcapMessageComponents.MULTIPLE_COMPONENT_TYPES {
run IPSMGWGenerateMTCorrelationId
run IPSMGWStoreRoutingInfoCassandra mode "store"
run IPSMGWAdjustRoutingInfoResponse
} else {
run IPSMGWStoreRoutingInfoCassandra mode "store"
}
}
End Session
Fetch IMSI
This feature uses an MSISDN to fetch the IMSI from the HLR via a SendRoutingInfoForSMRequest
Feature cheat sheet
Feature Name | Network Operator Data | Used in PlanId(s) | Stateful or Stateless | POJO Feature or SBB Feature |
---|---|---|---|---|
IPSMGWFetchIMSI |
No |
SMMA, Sh_PNR, MTFSM_PS_CS, register |
Stateless |
POJO |
Feature parameters
The Fetch IMSI feature supports the following parameters that may be passed in a feature execution script run statement:
Name | Allowed Values | Description |
---|---|---|
mode |
|
This is used to determine what action the feature should take when run. |
Session Input variables
The feature reads the following fields in Session State
Session State variable name | Variable type | Comments |
---|---|---|
MSISDN |
String |
The MSISDN to use in the SendRoutingInfoForSM operation |
Session Output variables
The feature sets the following fields in Session State
Session State variable name | Variable type | Comments |
---|---|---|
IMSI |
String |
The IMSI retrieved from the SendRoutingInfoForSM response |
SRI4SMResult |
enum |
Indicates if the SendRoutingInfoForSM request has succeeded. Allowed values are |
SRI4SMError |
TcapError |
The TcapError received in response to the SendRoutingInfoForSMRequest |
Statistics
IPSMGWFetchIMSI statistics are tracked by the sentinel.ipsmgw SBB and can be found under the following parameter set in REM:
SLEE-Usage → sentinel.ipsmgw service → sentinel.ipsmgw SBB → feature → IPSMGWFetchIMSI
or with rhino-stats:
"SLEE-Usage.Services.ServiceID[name=sentinel.ipsmgw,vendor=OpenCloud,version=3.1.0].SbbID[name=sentinel.ipsmgw,vendor=OpenCloud,version=3.1.0].feature.IPSMGWFetchIMSI"
Name | Description |
---|---|
SavedIMSI |
Incremented when we successfully retrieve the IMSI from the HLR |
SentSRIForSM |
Incremented when the SRIForSM is sent to the HLR |
FailedToSendSRIForSM |
Incremented when the SRIForSM fails to be sent to the HLR |
SuppressedSRIForSM |
Incremented when the SRIForSM is suppressed |
Configuration
The feature is configured with configuration scoped according to a Sentinel Selection Key. The Profile Table used to hold feature configuration is IPSMGWSharedConfigProfileTable
.
The following attributes are available
Attributes | Type | Meaning |
---|---|---|
HlrAddress |
String |
Address of the HLR to request the IMSI from, used when establishing the MAP dialog if |
UseMsisdnAsHlrAddress |
Boolean |
Controls whether to address the outbound HLR leg using a GT address formed from the subscriber MSISDN, instead of using the configured |
SentinelOriginatingAddress |
String |
Address of Sentinel used when establishing the MAP dialog |
SentinelIPSMGWAddress |
String |
The IP-SM-GW address that the feature will include it in MAP SendRoutingInfoForSMRequest request to send to HLR |
SriSmDeliveryNotIntended |
Boolean |
If true, specify the SmDeliveryNotIntended flag when performing an SRI for SM IMSI-only query (i.e. during SMMA callflows). |
SuppressHLRInteraction |
boolean |
If true, no MAP messages will be sent to the HLR. Can only be set to true when DeliveryOrder is PS_ONLY. For more information, refer to Suppression of HLR Interaction |
Using MSISDN as HLR Address
The Fetch IMSI feature can optionally address the HLR leg using a GT address formed from the inbound subscriber MSISDN, as opposed to using the destination addresses configured in the IPSMGWMapProxyConfigProfileTable
profile table described above.
This behaviour can be enabled or disabled by setting the UseMsisdnAsHlrAddress
attribute in the Shared Configuration Profile
.
MAP Application Context
The feature uses MAP Application Context shortMsgGatewayContext_v2_ac
. This application context was added in GSM MAP Phase 2.
If SriSmDeliveryNotIntended is set to true , the feature will create a MAP v3 dialog instead of a v2 dialog. Only enable this configuration if this parameter is supported by the configured HLR. |
Behaviour
When run with mode fetch
the FetchIMSI feature will read the MSISDN out of session state. It is then used to send a SendRoutingInfoForSMRequest
to the HLR. The request always has the SM-RP-PRI flag set to TRUE, and optionally has smDeliveryNotIntended set to "only IMSI requested" (based on the SriSmDeliveryNotIntended configuration flag).
When run with mode response
the feature will look for the receipt of the SendRoutingInfoForSMResponse, it extracts the IMSI and sets it in session state. If the SendRoutingInfoForSMRequest results in an error response then it will set the SRI4SMResult and SRI4SMError session state fields instead.
If the feature is run without a mode
parameter it returns a Feature Error.
The feature can be inhibited if the IPSMGW is configured to suppress HLR Interaction (see Suppression of HLR Interaction)
IPSMGW Extract Network Info Feature
This feature determines Mobile Country Code (MCC), Mobile Network Code (MNC), and ISO Country Code values for the subscriber.
This data can then be included in Credit Control Requests (CCR)s by mappers and Call Detail Records (CDR)s by the AVP CDR feature.
This feature is an extension of the Sentinel SIP Extract Network Info feature. It implements the same behaviour as that feature for SIP message triggers, but also includes behaviour for dealing with TCAP message triggers.
Feature cheat sheet
Feature Script Name |
IPSMGWExtractNetworkInfo |
---|---|
Call-Type |
Orig or Term |
Session Plan |
default, MOFSM, SMMA, MTFSM_PS_CS, MTFSM_CS_PS, MTFSM_PS, MTFSM_DR, MTFSM_CS |
Execution Points |
Post_SipAccess_SubscriberCheck, Post_SubscriptionSubscriberCheck, Post_SipTransaction_SubscriberCheck, Post_SipThirdPartyAccess_SubscriberCheck |
Network Operator Config |
Yes |
Subscriber Config |
No |
POJO or SBB |
POJO |
Feature FSMs |
None |
Feature Parameters |
None |
SAS Support |
Yes |
RA Entity Links |
None |
Session State Inputs and Outputs
This feature uses all of the session state fields of its parent feature. For a list of these, see that features documentation.
In addition, it uses the following fields:
Statistics
IPSMGWExtractNetworkInfo statistics are tracked by the sentinel.ipsmgw SBB and can be found under the following parameter set in REM:
SLEE-Usage → sentinel.ipsmgw service → sentinel.ipsmgw SBB → feature → IPSMGWExtractNetworkInfo
or with rhino-stats:
"SLEE-Usage.Services.ServiceID[name=sentinel.ipsmgw,vendor=OpenCloud,version=3.1.0].SbbID[name=sentinel.ipsmgw,vendor=OpenCloud,version=3.1.0].feature.IPSMGWExtractNetworkInfo"
Name | Type | Description |
---|---|---|
Started |
Counter |
Incremented when the feature is triggered. |
FailedToStart |
Counter |
Incremented when the feature fails to start. |
FailedDuringExecution |
Counter |
Incremented when the feature fails while executing. |
IssuedWarning |
Counter |
Incremented when the feature issues a warning. |
TimedOut |
Counter |
Incremented when the feature times out during execution. |
AccessNetworkMccMncFoundInTrigger |
Counter |
Incremented when access network MCCs and MNCs are found in the triggering message. |
AccessNetworkMccMncFoundInRegistrationData |
Counter |
Incremented when access network MCCs and MNCs are found in registration data. |
CellularNetworkMccMncFoundInTrigger |
Counter |
Incremented when access network MCCs and MNCs are determined from a Cellular-Network header on the triggering message. |
UnableToDetermineAccessNetworkMccMnc |
Counter |
Incremented when access network MCCs and MNCs cannot be determined. |
VisitedNetworkMccMncFoundInRegistrationData |
Counter |
Incremented when the visited network MCC and MNC are found in registration data. |
VisitedNetworkMccMncFoundInTrigger |
Counter |
Incremented when the visited network MCC and MNC are found in trigger. |
UnableToDetermineVisitedNetworkMccMnc |
Counter |
Incremented when the visited network MCC and MNC cannot be determined. |
IsoCountryCodeFoundFromHeader |
Counter |
Incremented when an ISO country code is extracted directly from an access network info header. |
IsoCountryCodeFoundFromMccMnc |
Counter |
Incremented when an ISO country code is determined from an MCC and MNC value. |
IsoCountryCodeFoundFromHomeNetworkConfig |
Counter |
Incremented when an ISO country code is determined from home network configuration in Sentinel. |
UnableToDetermineAccessNetworkIsoCountryCode |
Counter |
Incremented when an ISO country code cannot be determined. |
IgnoringTrigger |
Counter |
Incremented when trigger is not a TCAP message or SIP request. |
TcapTrigger |
Counter |
Incremented when the feature is triggered on a TCAP message. |
SipRequestTrigger |
Counter |
Incremented when the feature is triggered on a SIP request. |
ImsiMccMncFound |
Counter |
Incremented when MCC and MNC is found in IMSI. |
UnableToDetermineImsiMccMnc |
Counter |
Incremented when an MCC and MNC for the IMSI cannot be determined. |
Configuration
This feature uses the same configuration profiles as the Extract Network Info feature. See:
Provisioning interfaces
The feature is provisioned using the Sentinel IP-SM-GW feature REST API.
Behaviour
SIP Request Triggers
When triggered by a SIP request, this feature will execute its parent feature’s behaviour as described here: Extract Network Info - Behaviour
TCAP Message Triggers
The IPSMGWExtractNetworkInfo feature extracts MCCs and MNCs from:
-
The access and visited network info headers found in registration records. This requires the Registration Lookup From Cassandra feature to run before this feature.
-
The
IMSI
. This requires the Fetch IMSI feature to run before this feature.
The resulting information is recorded in session state for use by the AVP CDR Feature feature when writing a CDR, as well as the charging features when forming charging requests.
The following OpenCloud extension AVPs are used to communicate MCC and MNC information in CCRs and CDRs:
-
OC-ACCESS-NETWORK-MCC-MNC
-
OC-VISITED-NETWORK-MCC-MNC
-
OC-IMSI-NETWORK-MCC-MNC
-
3GPP-IMSI-NETWORK-MCC-MNC
For Sentinel AVP definitions, please refer to Sentinel AVP Definitions in the Sentinel Administration guide.
IPSMGW IEC Feature
The IPSMGW IEC charging feature defines immediate event charging of MO- and MT-FSMs delivered over the PS and CS networks for Sentinel as an IPSMGW.
Description
Feature script name |
IPSMGWIECFeature |
---|---|
Applicable contexts |
SIP service |
Prerequisite features |
PS Delivery or CS Delivery or MO Submission |
Feature execution points |
SipAccess_ChargingAbort SipAccess_CreditAllocatedPostCC SipAccess_CreditLimitReachedPostCC SipAccess_ControlNotRequiredPostCC SipAccess_ServiceTimer SipInstructionExecutionFailure SipThirdPartyAccess_SubscriberCheck SipThirdPartyAccess_PartyRequest SipThirdPartyAccess_PartyResponse SipTransaction_SubscriberCheck SipTransaction_Request SipTransaction_PartyResponse |
The IPSMGW IEC feature covers immediate event charging using a charge/refund model. The feature is responsible for:
-
creating the reservation charging instance (
IPSMGWChargingFeatureUtil.DEFAULT_IEC_CHARGING_INSTANCE
) and default session counter on a pending delivery. -
instructing the charging manager to send a direct debit to the OCS
-
detection of message nondelivery conditions and refunding as necessary
The general use case is that an SMS will be delivered by one of IPSMGW’s delivery or submission features. On the incoming MO SIP MESSAGE, or MT-FSM DialogTcapMessage, the IEC feature will trigger a direct debit, suspending the outgoing message until a charging response is received, before allowing the message to be sent. If a response to the message is received which indicates failure, a refund will be issued, unless a fallback is attempted that also has charging enabled.
For a high level overview of Sentinel charging see Sentinel SIP Charging Architecture
Currently, IPSMGW only supports one charging instance per Sentinel session, though this instance may have multiple session counters. |
All of IPSMGW’s charging features make use of Sentinel’s comprehensive charging API — see Using the SIP Charging Manager |
Feature cheat sheet
Feature Name | Network Operator Data | Used in PlanId(s) | Stateful or Stateless | POJO Feature or SBB Feature |
---|---|---|---|---|
IPSMGWIECFeature |
No |
MTFSM_PS,MTFSM_CS,MTFSM_CS_PS,MTFSM_PS_CS |
Stateless |
SBB |
Session state inputs and outputs
Inputs
Name | Format | Description | Behaviour if null/invalid |
---|---|---|---|
SentinelSelectionKey |
selection key (for example, |
For selecting mappers |
Increment InputParameterErrors Common cleanup actions |
SentinelIPSMGWAddress |
MAP-CommonDataTypes.AddressString |
The value that the feature will use as the MSC-address in outgoing messages. Written to SessionState for retrieval by charging mappers. |
N/A |
IPSMGWChargingCounterAddress |
key/value pairs identifying the session charged service |
Determines which counter the feature will update with charging data (the IEC feature only treats one counter as the immediate charging counter at a time). Also see Outputs. |
No-op unless initial request |
LatestOcsAnswer |
Last received CCA |
Passed through to a charging mapper to generate the session counter values |
Exception thrown, if the feature is expecting a response from the OCS. Otherwise ignored. |
PSDeliveryStatus |
NOT_ATTEMPTED/FAILED/SUCCEEDED |
Outcome of last PS Delivery attempt |
N/A |
CSDeliveryFailed |
boolean |
Whether the CS Delivery feature delivery attempt failed |
N/A |
MoSubmissionFailed |
boolean |
Whether the MOSubmission feature delivery attempt failed |
N/A |
PSDeliveryTimerID |
The ID of the PS Delivery timer |
Used in determining whether to do a refund after a delivery failure |
Timer event is ignored |
IECChargingInstructed |
boolean |
Whether there has already been a charging instruction in this session |
N/A |
IECRefundInstructed |
boolean |
Whether there has already been a refund instruction in this session |
N/A |
LatestClientRequest |
Credit-Control-Request |
Determine whether an incoming CCA is a direct debit |
N/A |
Outputs
Name | Format | Description |
---|---|---|
IPSMGWChargingCounterAddress |
key/value pairs identifying the session charged service |
Mapped from initial incoming chargeable event request in SIP initiated sessions to determine the default session counter against which the units will be charged. |
UserSessionId |
String |
The MT SIP session ID |
InboundSipRequest |
The incoming SIP request in MO deliveries |
Used to extract information for use in a CCR |
InboundDialogTcapMessage |
The incoming TCAP message in MT deliveries |
Used to extract information for use in a CCR |
IECChargingInstructed |
boolean |
Set after a |
IECRefundInstructed |
boolean |
Set after a |
Charging API interactions
The charging API interactions fall under the following categories:
-
charging instructions issued on the
IPSMGWChargingFeatureUtil.DEFAULT_IEC_CHARGING_INSTANCE
itself -
updates made to all counters on the charging instance, mainly limited to updates from CCAs.
-
complete implementation of event based charging on the default counter.
Interaction with the default charging instance
Initialisation
When the feature is first triggered on an incoming message, if there is a delivery message pending, it creates the default IEC charging instance, under the name IPSMGWChargingFeatureUtil.IPSMGW_IEC_CHARGING_INSTANCE
. It then maps the request to a session counter address written to the session state field IPSMGWChargingCounterAddress. This is the default session counter on which all subsequent IEC based charging is performed.
Initial debit
On any trigger other than an incoming message request, the feature checks whether the IPSMGWChargingFeatureUtil.DEFAULT_IEC_CHARGING_INSTANCE
has been initialised. The first step is to check the instance exists in the ChargingManager, then that the instance has a session counter with the address specified in session state IPSMGWChargingCounterAddress. If either check fails, the feature ends immediately on the assumption that IEC is not enabled.
The feature will instruct the charging instance to send a direct debit message to the OCS. It will suspend the outgoing delivery leg until the OCS authorises the request.
The Ro Credit-Control-Request is generated using the IPSMGWChargingInstanceToCCR mapper.
Interaction with all session counters
When a CCA is received, all counters on the ChargingInstance will be processed according to the algorithm outlined in Counter update algorithm pseudo code. The feature will clear the pending requested units on all session counters.
When charging using a non-default counter, another feature will need to set reported used and pending requested units on the counters as needed.
Mappers
This feature relies on two mappers:
-
The first converts the initial message to a SessionCounterAddress.
The default implementations are MTFSMToSessionCounterAddress and `SipRequestToSessionCounterAddress`SipRequestToSessionCounterAddress:// a mapper that takes a DialogTcapMessage or SipRequest and generates a SessionCounterAddress. final Mapper<SentinelSipSessionState> mapper = getMapperLibrary().findMapper( getSessionState().getSentinelSelectionKey(), argClass, SessionCounterAddress.class, mappingPoint);
-
The second mapper converts a CCA into a list of session counters.
The default implementation is CCAtoSessionCounterList:// a mapper that takes a CreditControlAnswer and generates a List<SessionCounter>. final Mapper<SentinelSipSessionState> mapper = getMapperLibrary().findMapper( getSessionState().getSentinelSelectionKey(), CreditControlAnswer.class, List.class mappingPoint);
MAP Proxy
This MAP Proxy feature proxies MAP messages between two network elements, typically a Serving MSC (SMSC) and an MSC.
Description
The MAP proxy acts as an intermediary between two network elements, typically an SMSC and MSC. The MAP proxy manages two TCAP legs, one to each network element, and forwards messages received on each leg to the other linked leg.
The SCCP address
of the destination network element is found by searching the feature configuration using the Sentinel Selection Key
and the TCAP Application Context
of the initial Dialog Open Request.
The IPSMGW uses the Map Proxy feature in |
Feature cheat sheet
Feature Name | Network Operator Data | Used in PlanId(s) | Stateful or Stateless | POJO Feature or SBB Feature |
---|---|---|---|---|
IPSMGWMapProxy |
Yes |
SRI4SM |
Stateless |
POJO |
Session Input variables
The feature reads the following fields in Session State
Session State variable name | Variable type | Comments |
---|---|---|
MSISDN |
String |
The MSISDN to use for addressing the HLR by GT |
Statistics
IPSMGWMapProxy statistics can be found under the following parameter set in REM:
SLEE-Usage → sentinel.ipsmgw service → sentinel.ipsmgw SBB → feature → IPSMGWMapProxy
or with rhino-stats:
"SLEE-Usage.Services.ServiceID[name=sentinel.ipsmgw,vendor=OpenCloud,version=3.1.0].SbbID[name=sentinel.ipsmgw,vendor=OpenCloud,version=3.1.0].feature.IPSMGWMapProxy
Name | Description |
---|---|
NewProxyLeg |
Incremented when a new proxy scenario is started |
NoLegForTriggerAci |
Incremented when the proxy feature is triggered but there is no leg associated with the triggering ActivityContextInterface. This may happen if the triggering leg is detached by some other feature before the IPSMGWMapProxy feature starts |
NoProxyLeg |
Incremented when the proxy feature is triggered but there is no associated leg to proxy messages to. This may happen if the proxy leg is detached, or unlinked by some other feature before the IPSMGWMapProxy feature starts |
FailedtoCreateNewProxyLeg |
Incremented when there is any error creating a new proxy leg |
LegExistsOnNewProxyLeg |
Incremented when a new proxy leg cannot be created because a leg with the requested name already exists |
ProxyLegAlreadyLinked |
Incremented when there is an error linking the proxy leg to the triggering leg because the legs are already linked |
Configuration
The IPSMGWMapProxy can proxy to different destinations based on the triggering TCAP Application Context and the value of the Sentinel Selection key.
The first Profile Table used to hold feature configuration is Shared Configuration Profile
. The following attributes are used:
Attributes | Type | Meaning |
---|---|---|
UseMsisdnAsHlrAddress |
Boolean |
Address the outbound HLR leg using a GT address formed from the subscriber MSISDN, instead of using the configured |
UseGtAsCallingParty |
Boolean |
When accepting an OpenRequest, the SCCP responder address in the OpenAccept will, by default, be set to the value of the SCCP called party in the OpenRequest. If This is useful when the inbound sccp-called-party has been modified by a network element to use PCSSN routing, but GT routing is required for establishing the TCAP dialog. |
The second Profile Table used to hold feature configuration is IPSMGWMapProxyConfigProfileTable
. Entries in the table are indexed by a Sentinel Selection key that is qualified by a TCAP Application Context. The following attributes are available
Attributes | Type | Meaning |
---|---|---|
DestinationAddress |
String |
The SCCP Address of the destination MSC, used when |
In the example below, the IPSMGWMapProxy feature is configured so 'shortMsgGatewayContext' triggers for MAP 1, 2 or 3 are proxied to 'type=C7,ri=pcssn,pc=5,ssn=6'.
Profile Name | DestinationAddress |
---|---|
${platform.operator.name}:::::map:shortMsgGatewayContext-v3-ac |
type=C7,ri=pcssn,pc=5,ssn=6 |
${platform.operator.name}:::::map:shortMsgGatewayContext-v2-ac |
type=C7,ri=pcssn,pc=5,ssn=6 |
${platform.operator.name}:::::map:shortMsgGatewayContext-v1-ac |
type=C7,ri=pcssn,pc=5,ssn=6 |
Using MSISDN as Destination Address
The MAP Proxy feature can optionally address the HLR leg using a GT address formed from the inbound subscriber MSISDN, as opposed to using the destination addresses configured in the IPSMGWMapProxyConfigProfileTable
profile table described above.
This behaviour can be enabled or disabled by setting the UseMsisdnAsHlrAddress
attribute in the Shared Configuration Profile
.
Modify SRI Leg
This Modify SRI Leg feature modifies outbound messages sent between two network elements, typically a Serving MSC (SMSC) and an MSC.
Description
The Modify SRI Leg feature acts as an intermediary between two network elements, typically an SMSC and MSC. The feature modifies outbound Send Routing Info for SM requests, and/or discards outbound InformSC requests based on configuration. This is primarilly intended for use with the Map Proxy Feature to ensure that outbound SendRoutingInfoForSM messages have SM RP PRI set to true, and to ensure InformSC requests are not proxied.
The IPSMGW uses the Modify SRI Leg feature in |
Feature cheat sheet
Feature Name | Network Operator Data | Used in PlanId(s) | Stateful or Stateless | POJO Feature or SBB Feature |
---|---|---|---|---|
IPSMGWModifySRILeg |
Yes |
SRI4SM |
Stateless |
POJO |
Statistics
IPSMGWModifySRILeg statistics can be found under the following parameter set in REM:
SLEE-Usage → sentinel.ipsmgw service → sentinel.ipsmgw SBB → feature → IPSMGWModifySRILeg
or with rhino-stats:
"SLEE-Usage.Services.ServiceID[name=sentinel.ipsmgw,vendor=OpenCloud,version=3.1.0].SbbID[name=sentinel.ipsmgw,vendor=OpenCloud,version=3.1.0].feature.IPSMGWMapProxy
Name | Description |
---|---|
InformSCDiscarded |
Incremented when an outbound InformSC is discarded. |
SMRPPRIForced |
Incremented when an outbound SentRoutingInfoForSM request has the Sm_RP_PRI field forced to true. |
GPRSSupportIndicatorRemoved |
Incremented when an outbound SentRoutingInfoForSM request has the GPRS Support indicator removed. |
Configuration
The feature configuration is in a Profile Table called IPSMGWModifySRILegConfigProfileTable
. Entries in the table are indexed by a Sentinel Selection key. The following attributes are available
Attributes | Type | Meaning |
---|---|---|
DiscardInformSC |
boolean |
If true, discard outbound InformSC components |
ForceSMRPPRI |
boolean |
If true, force Sm_RP_PRI to be set to true in SendRoutingInfoForSM requests |
In the example below, the IPSMGWModifySRILeg feature is configured so InformSC messages are discarded, but SendRoutingInfoForSM messages are sent unmodified.
Profile Name |
DiscardInformSC |
ForceSMRPPRI |
${platform.operator.name}:::: |
true |
false |
Ready For SM
This feature uses an IMSI to send a ReadyForSM to the HLR and handles the response
Feature cheat sheet
Feature Name | Network Operator Data | Used in PlanId(s) | Stateful or Stateless | POJO Feature or SBB Feature |
---|---|---|---|---|
IPSMGWReadyForSM |
No |
SMMA, Sh_PNR, register |
Stateless |
POJO |
Session Input variables
The feature reads the following fields in Session State
Session State variable name | Variable type | Comments |
---|---|---|
IMSI |
String |
The IMSI to use in the ReadyForSM operation |
MSISDN |
String |
The MSISDN to use for addressing the HLR by GT |
SRI4SMResult |
enum |
Indicates if the SendRoutingInfoForSM request has succeeded. Allowed values are |
Session Output variables
The feature sets the following fields in Session State
Session State variable name | Variable type | Comments |
---|---|---|
ReadyForSMResult |
enum |
Indicates if the ReadyForSM request has succeeded. Allowed values are |
ReadyForSMError |
TcapError |
The TcapError received in response to the ReadyForSM |
Statistics
IPSMGWReadyForSM statistics are tracked by the sentinel.ipsmgw SBB and can be found under the following parameter set in REM:
SLEE-Usage → sentinel.ipsmgw service → sentinel.ipsmgw SBB → feature → IPSMGWReadyForSM
or with rhino-stats:
"SLEE-Usage.Services.ServiceID[name=sentinel.ipsmgw,vendor=OpenCloud,version=3.1.0].SbbID[name=sentinel.ipsmgw,vendor=OpenCloud,version=3.1.0].feature.IPSMGWReadyForSM"
Name | Description |
---|---|
SentReadyForSM |
Incremented when the ReadyForSM message is successfully sent to the HLR |
FailedToSendReadyForSM |
Incremented when the ReadyForSM message fails to be sent to the HLR |
NoIMSIAvailable |
Incremented when the IMSI was not available from session state |
SRI4SMFailed |
Incremented when the SendRoutingInfoForSMRequest failed and the feature cannot do anything as a result |
SuppressedReadyForSM |
Incremented when the ReadyForSM message is suppressed |
Configuration
The feature is configured with configuration scoped according to a Sentinel Selection Key. The Profile Table used to hold feature configuration is IPSMGWSharedConfigProfileTable
.
The following attributes are available
Attributes | Type | Meaning |
---|---|---|
HlrAddress |
String |
Address of the HLR to send the ReadyForSM request, used when establishing the MAP dialog if |
UseMsisdnAsHlrAddress |
boolean |
Controls whether to address the outbound HLR leg using a GT address formed from the subscriber MSISDN, instead of using the configured |
SentinelOriginatingAddress |
String |
Address of Sentinel used when establishing the MAP dialog |
InvokeTimeout |
int |
The timeout in milliseconds for the response from HLR. Used in the TCAP layer for the invoke timeout. Default is 5000 |
SuppressHLRInteraction |
boolean |
If true, no MAP messages will be sent to the HLR. Can only be set to true when DeliveryOrder is PS_ONLY. For more information, refer to Suppression of HLR Interaction |
Using MSISDN as HLR Address
The Ready For SM feature can optionally address the HLR leg using a GT address formed from the inbound subscriber MSISDN, as opposed to using the destination addresses configured in the IPSMGWMapProxyConfigProfileTable
profile table described above.
This behaviour can be enabled or disabled by setting the UseMsisdnAsHlrAddress
attribute in the Shared Configuration Profile
.
MAP Application Context
The feature uses MAP Application Context mwdMngtContext_v2_ac
. This application context was added in GSM MAP Phase 2.
Behaviour
When triggered on a TCAP message the feature checks that an IMSI is present in session state field named IMSI. It then initiates a ReadyForSM operation to the HLR with an alert reason of:
-
Memory Available
if session Plan Id isSMMA
-
MS Present
if session Plan Id isSh_PNR
orregister
When the ReadyForSM operation completes, the feature sets the ReadyForSMResult
session state field based on the response, SUCCESS
if the ReadyForSM operation is successful, FAILED
if the ReadyForSM operation returns an error or a timeout. It also sets the ReadyForSMError
session state field with the TcapError if the response was a failure.
It can be inhibited if the IPSMGW is configured to suppress HLR Interaction (see Suppression of HLR Interaction)
Reject Dialog
SCCP Whitelist
Description
Feature name |
IPSMGWSCCPWhitelist |
---|---|
Applicable contexts |
IPSMGW service |
Prerequisite features |
None |
The IPSMGW SCCP Whitelist Feature rejects OpenRequests from SCCP addresses it does not recognize based on a provisioned whitelist.
Request from non-GT addresses will be allowed without checking the whitelist. If a whitelist is not found, the feature ends immediately, allowing call processing to continue. If the whitelist is then found to be empty, the feature ends, allowing call processing to continue. If the originating address contains GT digits, it will match those against the provisioned whitelist using the list’s configured address search mode. If a match is not found, the incoming leg is released via endSession.
Feature cheat sheet
Feature Name | Network Operator Data | Used in PlanId(s) | Stateful or Stateless | POJO Feature or SBB Feature |
---|---|---|---|---|
IPSMGWSCCPWhitelist |
No |
SRI4SM,MTFSM_PS_CS,MTFSM_CS_PS,MTFSM_PS,MTFSM_CS |
Stateless |
POJO |
Session state inputs and outputs
Error scenarios
Scenario | Handling |
---|---|
Trigger event not a TCAPMessage |
Report featureCannotStart |
TCAP open request is null |
Report featureCannotStart |
Sessionstate SentinelSelectionKey is null |
Report featureCannotStart |
Trigger is null |
Report featureCannotStart |
OrigAddr in DialogOpenRequestEvent is null |
Report featureCannotStart |
Feature responses
Response | Reason |
---|---|
featureCannotStart |
Trigger event must be DialogOpenRequestEvent, SessionState SentinelSelectionKey is not set, unsupported trigger, originating SCCP address not present in DialogOpenRequestEvent |
featureHasFinished |
feature has finished |
Configuration
The feature uses the following profile table to configure IPSMGWSCCPWhitelist.
Configuration profile naming
Configuration Profile Table Name | Description | Profile Naming |
---|---|---|
${PLATFORMOPERATOR}_Sentinel_AddressListConfigurationTable |
Address list configuration |
${SELECTIONKEY}:IPSMGWSCCPWhitelist:AddressList |
${PLATFORMOPERATOR}_Sentinel_AddressListEntryTable |
Sentinel Address List entry table |
${SELECTIONKEY}:IPSMGWSCCPWhitelist:AddressList:${ADDRESS} |
Provisioning interfaces
The feature is provisioned using the Sentinel Sentinel Core REST API.
Mobile Originated Features
These features relate to the SMS Submission path from the UE to the network.
Feature | What it does |
---|---|
submits an SMS Over IP request to the SMSC. |
|
updates the Orig-Address of outbound MAP MT-ForwardSM requests to allow CAP charging of the session. |
|
sends an SMS Submit Report to an SMS over IP capable UE |
MO Submission
This feature submits an SMS Over IP request to the SMSC.
Feature cheat sheet
Feature Name | Network Operator Data | Used in PlanId(s) | Stateful or Stateless | POJO Feature or SBB Feature |
---|---|---|---|---|
IPSMGWMOSubmission |
No |
MOFSM |
Stateless with FSM encoded into session state |
POJO |
Statistics
MOSubmission statistics are tracked by the sentinel.ipsmgw SBB and can be found under the following parameter set in REM:
SLEE-Usage → sentinel.ipsmgw service → sentinel.ipsmgw SBB → feature → IPSMGWMOSubmission
or with rhino-stats:
"SLEE-Usage.Services.ServiceID[name=sentinel.ipsmgw,vendor=OpenCloud,version=3.1.0].SbbID[name=sentinel.ipsmgw,vendor=OpenCloud,version=3.1.0].feature.IPSMGWMOSubmission"
Name | Description |
---|---|
OpenRequestSent |
Incremented when OpenRequest is sent to SMSC |
FailedToSendOpenRequest |
Incremented when the feature fails to send OpenRequest to SMSC |
ForwardSMSent |
Incremented when a MO ForwardSMReq is sent to SMSC |
ForwardSMSuccessResponse |
Incremented when the feature gets the MO ForwardSMResp from SMSC |
Configuration
The feature is configured with configuration scoped according to a Sentinel Selection Key. The Profile Table used to hold feature configuration is IPSMGWSharedConfigProfileTable
.
The following attributes are available
Attributes | Type | Meaning |
---|---|---|
HlrAddress |
String |
Address of the HLR to request the MSRN from, used when establishing the MAP dialog |
TemplateSmscAddress |
String |
Contains a Template SMSC SCCP Address, where the digits are replaced by the received SMSC address |
SentinelOriginatingAddress |
String |
Address of Sentinel used when establishing the MAP dialog |
SentinelIPSMGWAddress |
String |
The IP-SM-GW address that the feature will include it in MAP AnyTimeModification request to send to HLR |
InvokeTimeout |
int |
The timeout in milliseconds for the response from HLR. Used in the TCAP layer for the invoke timeout. Default is 5000 |
SmsContentSizeThreshold |
int |
The maximum number of octets that a SMS message is allowed to contain to send the message as part of the TC_BEGIN as described below |
ChargingOptions |
String[] |
If this array contains the value |
MAP Application Context
The feature uses MAP Application Context shortMsgMO_RelayContext_v2_ac
. This application context was added in GSM MAP Phase 2.
Behaviour
The feature is triggered upon receipt of a SIP Message request.
The feature first checks that the SIP Message request’s Content-Type header is "application/vnd.3gpp.sms". If not, the feature finishes execution.
If the SIP Message request has a Content-Type header of "application/vnd.3gpp.sms" the feature extracts the body and parses it into an RP Message of the appropriate type. If the RP Message can be parsed, the feature extracts the SMSC address from the parsed RP Message. The feature then extracts the SMSC Address from the parsed RP Message. The further behaviour of the feature depends on whether online charging is enabled or not. If online charging is not enabled the feature immediately sends a 202 Accepted response to the SIP Message request, otherwise it will only send it after a successful online charging response.
Once the SMS has been accepted, the feature passes the SMS into the SMSC. This is through the use of the MAP MO Forward SM operation, on the shortMsgMO_RelayContext_v2_ac
MAP Application Context.
A general overview of the feature behaviour is depicted in the diagram below.
Submitting the SMS to the SMSC
There are two different flows where the feature can submit the SMS. Note both of these flows assume that the 202 response above has been sent.
The first is for an SMS that is sufficiently small according to the configured SmsContentSizeThreshold
attribute to fit both the MAP_OPEN
request and content of the MAP_MO_FORWARD_SHORT_MESSAGE
request in a single TCAP Message.
The second is for an SMS that is too large to fit both the MAP_OPEN
request and content of the MAP_MO_FORWARD_SHORT_MESSAGE
request in a single TCAP Message.
MO Submission Location
This feature updates the Orig-Address of outbound MAP MT-ForwardSM requests to allow CAP charging of the session.
Feature cheat sheet
Feature Name | Network Operator Data | Used in PlanId(s) | Stateful or Stateless | POJO Feature or SBB Feature |
---|---|---|---|---|
IPSMGWMOSubmissionLocation |
No |
MOFSM |
Stateless |
POJO |
Session state inputs and outputs
Inputs
Name | Type | Purpose |
---|---|---|
PaniMccsMncs |
List<com.opencloud.sentinel.common.MccMnc> |
A list of |
IsoCountryCode |
String |
The ISO Country Code for the session. The |
Statistics
MOSubmissionLocation statistics are tracked by the sentinel.ipsmgw SBB and can be found under the following parameter set in REM:
SLEE-Usage → sentinel.ipsmgw service → sentinel.ipsmgw SBB → feature → IPSMGWMOSubmissionLocation
or with rhino-stats:
"SLEE-Usage.Services.ServiceID[name=sentinel.ipsmgw,vendor=OpenCloud,version=3.1.0].SbbID[name=sentinel.ipsmgw,vendor=OpenCloud,version=3.1.0].feature.IPSMGWMOSubmissionLocation"
Name | Description |
---|---|
UseGeneratedGTAsOutgoingOriginatingAddress |
Incremented when a GT is successfully generated from the |
UseUnknownGTAsOutgoingOriginatingAddress |
Incremented when a GT can not be generated from the |
Configuration
The feature is configured with configuration scoped according to a Sentinel Selection Key. The MOSubmissionLocation feature refers to two tables for configuration. The Profile Table is used to hold feature configuration is MOSubmissionLocationProfileTable
.
The following attributes are available
Attributes | Type | Meaning |
---|---|---|
UseGeneratedGTAsOriginatingAddress |
Boolean |
Modify the OrigAddress of the outbound MTForwardSM request |
The second Profile Table CapChargingProfileTable
holds CAP Charging specific configuration. The following attributes are used:
Attributes | Type | Meaning |
---|---|---|
ChargingGTFormatString |
String |
The format template to use when creating Charging GTs. It must be a digit string except for tokens ('{iso}', '{mcc}', '{mnc}) which are substituted in. |
UnknownChargingGT |
String |
The Charging GT to use when one could not be generated because the user’s location could not be determined |
Behaviour
The feature retrieves the TCAP leg IPSMGWMOSubmission
created by the MO Submission feature. If the leg is available the feature attempts to generate a Charging GT using the ChargingGTFormatString
and sets the OrigAddress
of the outboud TCAP message with the generated value. If this fails, the feature uses the UnknownLocationChargingGT
for the OrigAddress
.
Generating Charging GTs
The feature uses the CAP Charging Component to generate Charging GTs based on location data.
Provisioning interfaces
The feature is provisioned using the Sentinel IP-SM-GW feature REST API.
MO Submit Report
This feature sends an SMS Submit Report to an SMS over IP capable UE
Feature cheat sheet
Feature Name | Network Operator Data | Used in PlanId(s) | Stateful or Stateless | POJO Feature or SBB Feature |
---|---|---|---|---|
IPSMGWMOSubmitReport |
Yes |
MOFSM |
Stateless |
POJO |
Statistics
MOSubmitReport statistics are tracked by the sentinel.ipsmgw SBB and can be found under the following parameter set in REM:
SLEE-Usage → sentinel.ipsmgw service → sentinel.ipsmgw SBB → feature → IPSMGWMOSubmitReport
or with rhino-stats:
"SLEE-Usage.Services.ServiceID[name=sentinel.ipsmgw,vendor=OpenCloud,version=3.1.0].SbbID[name=sentinel.ipsmgw,vendor=OpenCloud,version=3.1.0].feature.IPSMGWMOSubmitReport"
Name | Description |
---|---|
ErrorSendingMessage |
Incremented when the feature fails to send SIP MESSAGE containing smsSubmitReport |
SentAck |
Incremented when the feature sends one RP-ACK in the SIP MESSAGE |
SentError |
Incremented when the feature sends one RP-ERROR in the SIP MESSAGE |
ReceivedOk |
Incremented when the feature receives the successful response for the MESSAGE request |
ReceivedError |
Incremented when the feature receives non-successful response for the MESSAGE request |
Configuration
The feature is configured with configuration scoped according to a Sentinel Selection Key. The Profile Table used to hold feature configuration is Shared Configuration Profile
. The following attributes are used:
Attributes | Type | Meaning |
---|---|---|
ICSCFURI |
String |
The I-CSCF SIP URI that will be used to route outbound SIP MESSAGE requests (see SIP Transports and Routing) |
Behaviour
The feature is triggered after the MO Submission feature has finished.
The feature checks session state to determine the outcome of MO Submission to the SMSC.
In the case that MO Submission was successful it formulates a SIP Message request containing an RP-ACK towards the initiating UE. In the case that there were parsing or other issues in MO Submission it formulates a SIP Message request containing an RP-ERROR towards the initiating UE (SM-over-IP sender).
The details of these requests are as follows.
Generic header setting
Regardless of whether or not the Submit Report towards the UE (SM-over-IP sender) indicates a successful or failed submission attempt the following headers are set
Header | Setting or manipulation |
---|---|
Request URI |
Contains a public user identity of the SM-over-IP sender |
Route header |
Set to the I-CSCF URI, with the loose routing parameter added |
Content-Type |
set to "application/vnd.3gpp.sms" |
It reads the P-Asserted-Identity
, P-Preferred-Identity
and From
headers of the original SMS over IP Message request in order to set the Request URI of the Submit Report.
Creation of an RP-ACK Submit report
In addition to the generic header setting, an RP-ACK Submit report sets headers as follows
Header | Setting or manipulation |
---|---|
P-Asserted-Identity |
Contains the SIP URI of the IP-SM-GW |
Request-Disposition |
set to "fork" |
Message body |
Contains an RP-ACK in content transfer encoding of type "binary" |
The RP Message Reference in the RP-ACK matches the Message Reference in the RP-Submit.
Creation of an RP-ERROR Submit report
In addition to the generic header setting, an RP-ERROR Submit report sets the body of the SIP Message request to contain an RP-ERROR, with content transfer encoding of type "binary".
The RP Message Reference in the RP-ERROR matches the Message Reference in the RP-Submit.
The setting of the RP-ERROR’s RPCause value is as follows
Source error cause | RP Error Cause value |
---|---|
Could not parse the SMS body from the SM-over-IP sender |
PROTOCOL_ERROR |
MO Forward SM resulted in TC_UserAbort |
NETWORK_OUT_OF_ORDER |
MO Forward SM resulted in TC_ProviderAbort |
NETWORK_OUT_OF_ORDER |
MO Forward SM resulted in an InvokeTimeout |
NETWORK_OUT_OF_ORDER |
MO Forward SM error MAPErrors.facilityNotSupported |
REQUESTED_FACILITY_NOT_IMPLEMENTED |
MO Forward SM error MAPErrors.systemFailure |
NETWORK_OUT_OF_ORDER |
MO Forward SM error MAPErrors.unexpectedDataValue |
SEMANTICALLY_INCORRECT_MESSAGE |
MO Forward SM error Delivery Failure with Delivery Failure Cause of memoryCapacityExceeded |
MEMORY_CAPACITY_EXCEEDED |
MO Forward SM error Delivery Failure with Delivery Failure Cause of equipmentProtocolError |
PROTOCOL_ERROR |
MO Forward SM error Delivery Failure with Delivery Failure Cause of equipmentNotSM_Equipped |
REQUESTED_FACILITY_NOT_IMPLEMENTED |
MO Forward SM error Delivery Failure with Delivery Failure Cause of unknownServiceCentre |
UNASSIGNED_NUMBER |
MO Forward SM error Delivery Failure with Delivery Failure Cause of sc_Congestion |
CONGESTION |
MO Forward SM error Delivery Failure with Delivery Failure Cause of invalidSME_Address |
SHORT_MESSAGE_TRANSFER_REJECTED |
MO Forward SM error Delivery Failure with Delivery Failure Cause of subscriberNotSC_Subscriber |
UNIDENTIFIED_SUBSCRIBER |
Mobile Terminated Features
These features relate to the SMS Delivery path from the network to the UE.
The SMS delivery path for the IP-SM-GW includes two initiation points:
-
receipt of Send Routing Info for SM
-
receipt of MT Forward Short Message
For information related to the delivery policies implemented, please refer to About SMS delivery in the Administration guide.
Feature | What it does |
---|---|
modifies the MSC address in Send Routing Info For SM responses to be the configured address of the IPSMGW. This ensures that subsequent MAP MT Forward Short Message requests are sent to the IPSMGW. |
|
stores SMS routing information in Cassandra. The stored data includes additional correlation information. |
|
retrieves Circuit Switched routing information from the Cassandra Database and stores it into session state. |
|
reads Third Party Registration information stored in the Cassandra Database, and writes it into session state. |
|
delivers an SMS encapsulated in SIP (SMS Over IP) to the UE |
|
delivers a Short Message towards the MSC or SGSN, performing TCAP application context negotiation as necessary |
|
generates a correlation IMSI when responding to a SRI request. It uses the Correlation Resource Adaptor to allocate an IMSI based on the MCC and MNC. |
|
increments (or creates) a row in the Cassandra cluster for the current MSISDN, to be used as the RP Message Reference, writing the value into session state. |
|
links incoming SIP delivery reports with the sentinel session that the delivery report is responding to. |
|
generates a response to a SRI for SM request when the system is configured to attempt PS delivery only. |
Preserve Call Id Over B2BUA
The SIP B2BUA feature can be configured to preserve the Call-ID
header across both legs of a B2BUA’d session. Certain MT flows require the correlation of an incoming request with an existing IP-SM-GW session. This is achieved using the In-Reply-To
header of the incoming request. Depending on network configuration this may require the preservation of the Call-ID
header when B2BUA’ing the MESSAGE request onwards. By default and in typical deployments, this behavior is not configured. It should only be configured if required. For more information on this configuration option read the B2BUA Feature Configuration documentation.
Adjust Routing Info Response
This feature modifies the MSC address in Send Routing Info For SM responses to be the configured address of the IPSMGW. This ensures that subsequent MAP MT Forward Short Message requests are sent to the IPSMGW.
Feature cheat sheet
Feature Name | Network Operator Data | Used in PlanId(s) | Stateful or Stateless | POJO Feature or SBB Feature |
---|---|---|---|---|
IPSMGWAdjustRoutingInfoResponse |
No |
SRI4SM |
Stateless |
POJO |
Configuration
The feature is configured using the IPSMGW Service configuration. The Profile Table used to hold feature configuration is Shared Configuration Profile
. The following attributes are relevant
Attributes | Type | Meaning |
---|---|---|
SentinelIPSMGWAddress |
String |
The value that the feature will use as the MSC-address in outgoing messages. |
Behaviour
The feature is triggered upon receipt of a third-party response message. The message is unmodified if it is not a successful Send Routing Info For SM response. The feature handles the following application contexts: shortMsgGatewayContext_v1_ac, shortMsgGatewayContext_v2_ac, shortMsgGatewayContext_v3_ac
When processing a v1/v2 MAPSendRoutingInfoForSMRes, the feature will set the MSC address in the outgoing message to the value of the SentinelIPSMGWAddress configured in the IPSMGW service config profile. When processing a v3 MAPRoutingInfoForSM_Res, the feature will set outgoing message’s 'GPRS Supported' indicator to false and set the NetworkNodeNumber and AdditionalNumber to the value of the SentinelIPSMGWAddress.
This ensures that the MAP MT Forward Short Message is then delivered to the IPSMGW.
CS Delivery
This feature delivers a Short Message towards the MSC or SGSN, performing TCAP application context negotiation as necessary
Feature cheat sheet
Feature Name | Network Operator Data | Used in PlanId(s) | Stateful or Stateless | POJO Feature or SBB Feature |
---|---|---|---|---|
IPSMGWCSDelivery |
No |
MTFSM_CS,MTFSM_CS_PS,MTFSM_PS_CS |
Stateful |
POJO |
MAP Phases and Application Contexts
The feature can be triggered by MAP Forward Short Message on the terminating path, for MAP Phases 1, 2 and 2+. This is referred to as MT Forward Short Message
or MT-FSM for short.
The MAP Phases 1, 2 and 2+ are sometimes referred to as "v1, v2 and v3" however such language is not strictly correct.
From a TCAP Application Context perspective:
-
MAP Phase 2 defines
shortMsgMT_RelayContext_v2_ac
- this is sometimes referred to as "v2" -
MAP Phase 2+ defines
shortMsgMT_RelayContext_v3_ac
- this is sometimes referred to as "v3" -
and MAP Phase 1 does not use a TCAP Application Context. In the software this case is represented by a synthetic application context
shortMsgMT_RelayContext_v1_ac
. It is synthetic because it does not exist on the wire. This case is sometimes referred to as MAP "v1".
Statistics
IPSMGWCSDelivery statistics are tracked by the sentinel.ipsmgw SBB and can be found under the following parameter set in REM:
SLEE-Usage → sentinel.ipsmgw service → sentinel.ipsmgw SBB → feature → IPSMGWCSDelivery
or with rhino-stats:
"SLEE-Usage.Services.ServiceID[name=sentinel.ipsmgw,vendor=OpenCloud,version=3.1.0].SbbID[name=sentinel.ipsmgw,vendor=OpenCloud,version=3.1.0].feature.IPSMGWCSDelivery"
Name | Description |
---|---|
AttemptedV1Open |
Incremented when the feature has sent an OpenRequestV1. This corresponds to receipt of a TCAP TC_BEGIN without an Application Context. |
AttemptedV2Open |
Incremented when the feature has sent an OpenRequestV2. This corresponds to a TCAP TC_BEGIN with an Application Context from MAP Phase 2. |
AttemptedV3Open |
Incremented when the feature has sent an OpenRequestV3. This corresponds to receipt of a TCAP TC_BEGIN with an Application Context from MAP Phase 2+. |
FallbackToV1 |
Incremented when the feature has received an U-Abort instructing fallback to MAP Phase 1. |
FallbackToV2 |
Incremented when the feature has received an U-Abort instructing fallback to MAP Phase 2. |
SuccessfullyDeliveredV1 |
Incremented when the MSC responds to a v1 MTFSM with an error-less dialog close. |
SuccessfullyDeliveredV2 |
Incremented when the MSC responds to a v2 MTFSM with an error-less dialog close. |
SuccessfullyDeliveredV3 |
Incremented when the MSC responds to a v3 MTFSM with an error-less dialog close, optionally with an MTFSM-res. |
ErrorDeliveringV1 |
Incremented when the MSC responds to a v1 MTFSM with an error. |
ErrorDeliveringV2 |
Incremented when the MSC responds to a v2 MTFSM with an error, or when the MSC responds to a v2 dialog open with a refuse that does not indicate negotiation is possible. |
ErrorDeliveringV3 |
Incremented when the MSC responds to a v3 MTFSM with an error, or when the MSC responds to a v3 dialog open with a refuse that does not indicate negotiation is possible. |
FailedToSendOpen |
Incremented when the feature has failed to send any version of OpenRequest. |
FailedToSendMTFSM |
Incremented when the MTFSM cannot be sent after the dialog has been accepted. |
SentReportSMDeliveryStatus |
Incremented when the feature has sent ReportSMDeliveryStatus request to HLR. |
FailedToSendReportSMDeliveryStatus |
Incremented when the feature has failed to generate ReportSMDeliveryStatus request |
ReportSMSucceeded |
Incremented when the HLR responds to a ReportSMDeliveryStatus request with an error-less dialog close. |
ReportSMFailed |
Incremented when the HLR responds to a ReportSMDeliveryStatus request with an error. |
SystemError |
Incremented when the feature sends a generated SystemError as a response to the SMSC. |
Configuration
The feature is configured with configuration scoped according to a Sentinel Selection Key. Two Profile Tables are used for configuration. The first profile Table used to hold feature configuration is Shared Configuration Profile
. The following attributes are used:
Attributes | Type | Meaning |
---|---|---|
SentinelOriginatingAddress |
String |
The OriginatingAddress used to represent Sentinel when sending the forwardSM on to the destination MSC |
InvokeTimeout |
Long |
Timeout in ms when invoking MAP operations, for example 5000ms. |
DeliveryOrder |
Enum |
If PS Delivery will run after CS Delivery, there is no need to send error report to SMSC on CS delivery failure |
UseMsisdnAsHlrAddress |
Boolean |
Controls whether to address the outbound HLR leg using a GT address formed from the subscriber MSISDN, instead of using the configured |
TemplateSmscAddress |
String |
Contains a Template SMSC SCCP Address, where the digits are replaced by the received SMSC address |
The second Profile Table used to hold feature configuration is IPSMGWCSDeliveryConfigProfileTable
. The following attributes are used:
Attributes | Type | Meaning |
---|---|---|
DeliveryFallbackAvoidanceCodes |
int[] |
A list of error codes that if matched from the SM-DeliveryFailure will stop a PS fallback |
Behaviour
This feature is responsible for Circuit Switched delivery of a Short Message.
CS delivery is triggered in two ways:
-
Upon receipt of a ForwardSM message from the SMSC if a CS_ONLY or CS_THEN_PS
DeliveryOrder
is specified in Shared Configuration Profile -
A failed PS Delivery attempt where
DeliveryOrder
is PS_THEN_CS
After validating configuration and session state inputs, the CS Delivery feature takes the received ForwardSM (regardless of whether or not PS Delivery was attempted) and begins the TCAP Application Context Negotiation Flows.
ForwardSM
The feature uses the negotiated dialog for delivery of the ForwardSM, as described below:
CS_ONLY or PS_THEN_CS
When the DeliveryOrder
specified in Shared Configuration Profile is CS_ONLY or PS_THEN_CS, for a ForwardSM sent to MSC:
If | Then | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Charging is performed and returns a failure |
Error returned to SMSC in MT-FSM response |
||||||||||
Context negotiation fails |
System Error or OpenRefuse sent to SMSC |
||||||||||
MSC replies with Success |
ForwardSM Success sent to SMSC |
||||||||||
PS_THEN_CS delivery HLR replies with SendRoutingInfo Error |
ForwardSM AbsentSubscriber Error sent to SMSC and ReportSMDeliveryStatus sent to HLR with SM-DeliveryOutcome=absentSubscriber |
||||||||||
MSC replies with Error |
ForwardSM Error sent to SMSC
|
CS_THEN_PS
When the DeliveryOrder
specified in Shared Configuration Profile is CS_THEN_PS, for a ForwardSM sent to MSC:
If | Then | ||||||
---|---|---|---|---|---|---|---|
Charging is performed and returns a failure |
Error returned to SMSC in MT-FSM response |
||||||
Context negotiation fails |
PS-Delivery is initiated |
||||||
MSC replies with Success |
ForwardSM Success sent to SMSC |
||||||
MSC replies with Error other than a |
PS-Delivery is initiated
|
||||||
MSC replies with a |
|
Session state inputs and outputs
Inputs
Name | Type | Format | Description | Behaviour if null/invalid |
---|---|---|---|---|
SentinelSelectionKey |
com.opencloud.sentinel.common.SentinelSelectionKey |
selection key (for example, |
For selecting configuration data |
Report featureCannotStart, featureHasFinished |
MSISDN |
String |
The MSISDN to use in the ReportSMDeliveryStatus operation, and to use for GT routing if configured |
Unable to send ReportSMDeliveryStatus messages, and to route on GT if configured |
|
SRI4SMResAppContext |
String |
One of the following values |
This identifies the version of the saved SRI4SM to extract the MSC address from. |
NoRoutingInfoException: "Unable to fetch SRI from session state" |
SRI4SMResV1 |
MAPSendRoutingInfoForSMRes |
The full SRI4SMResV1 message |
Used to extract the MSC address from |
NoRoutingInfoException: "Unable to fetch SRI from session state" |
SRI4SMResV2 |
MAPSendRoutingInfoForSMRes |
The full SRI4SMResV2 message |
Used to extract the MSC address from |
NoRoutingInfoException: "Unable to fetch SRI from session state" |
SRI4SMResV3 |
MAPRoutingInfoForSM_Res |
The full SRI4SMResV3 message |
Used to extract the MSC address from |
NoRoutingInfoException: "Unable to fetch SRI from session state" |
MTFSMDeliveryOrder |
com.opencloud.sentinel.ipsmgw.shared.config.profile.DeliveryOrder |
One of |
Current DeliveryOrder based on configuration and available routing info, correpsonding to current selection key plan Id. |
Schedule MTFSM error response assuming that PS Delivery will not be attempted |
Only one of SRI4SMResV1, SRI4SMResV2, or SRI4SMResV3 will ever have any data in it. |
Outputs
Name | Type | Description |
---|---|---|
CSDeliveryAttempted |
boolean |
True if an OpenRequest was sent out in a delivery attempt |
CSDeliveryFailed |
boolean |
True if the feature failed to do a successful delivery for any reason |
FallbackAllowed |
boolean |
True if no SM-DeliveryFailure was received, or if the error cause in the SMDeliveryFailure was not a configured 'DeliveryFallbackAvoidanceCodes' value |
SM Delivery Failure Cause Mappings
These are the SM-EnumeratedDeliveryFailureCause
values that may used in the feature’s DeliveryFallbackAvoidanceCodes
configuration. Other values may be configured but are unlikely to appear in a SM-DeliveryFailure
message.
Cause | Value |
---|---|
|
0 |
|
1 |
|
2 |
|
3 |
|
4 |
|
5 |
|
6 |
Delivery Report Handover
This feature links incoming SIP delivery reports with the sentinel session that the delivery report is responding to.
Feature cheat sheet
Feature Name | Network Operator Data | Used in PlanId(s) | Stateful or Stateless | POJO Feature or SBB Feature |
---|---|---|---|---|
IPSMGWDeliveryReportHandover |
No |
MTFSM_DR |
Stateless |
SBB |
Statistics
IPSMGWGenerateMessageReference statistics are tracked by the sentinel.ipsmgw SBB and can be found under the following parameter set in REM:
SLEE-Usage → sentinel.ipsmgw service → IPSMGW Delivery Report Handover Feature SBB
or with rhino-stats:
"SLEE-Usage.Services.ServiceID[name=sentinel.ipsmgw,vendor=OpenCloud,version=3.1.0].SbbID[name=ipsmgw-delivery-report-handover-feature,vendor=OpenCloud,version=3.1.0]"
Statistic | Incremented when… |
---|---|
ACNameBindingError |
The incoming delivery report was not matched against an existing ApplicationContextInterface |
ACNameBindingFound |
The incoming delivery report was successfully matched against an existing ApplicationContextInterface |
Behaviour
The Delivery Report Handover feature is run as part of the PS delivery leg in the MT SMS flow. The PS Delivery feature will send an SMS over IP message. The call id of this message will be used to store the activity context of the session, using the Activity Context naming facility. On receipt of the message, the endpoint will generate a delivery report (with a message-type-indicator of RP_ACK or RP_ERROR) to indicate success or failure of the MT message. This delivery report message will be classified by the Determine Is SMS Over IP feature, and will trigger the Delivery Report Handover feature.
When the Delivery Report Handover feature is triggered on an incoming SIP Delivery Report, the feature extracts the value of the 'InReplyTo' header from the incoming SIP MESSAGE and searches for Application Contexts registered against that value in the ACI Naming Facility.
-
If a match is found, the triggering message is handed over to the original session - the PS delivery feature will be triggered in the original session, and it will process the Delivery Report. The session in which the Delivery Report Handover feature is running will be ended.
-
If no match is found, the session is ended with a 404.
Fetch Routing Info Cassandra
This feature retrieves Circuit Switched routing information from the Cassandra Database and stores it into session state.
Feature cheat sheet
Feature Name | Network Operator Data | Used in PlanId(s) | Stateful or Stateless | POJO Feature or SBB Feature |
---|---|---|---|---|
IPSMGWFetchRoutingInfoCassandra |
Yes |
MTFSM_PS,MTFSM_CS,MTFSM_PS_CS,MTFSM_CS_PS |
Stateless |
POJO |
Session Input variables
The feature reads the following fields in Session State
Session State variable name | Variable type | Comments |
---|---|---|
MTFSMDeliveryOrder |
com.opencloud.sentinel.ipsmgw.shared.config.profile.DeliveryOrder |
One of |
Session output variables
The IPSMGWFetchRoutingInfoCassandra feature populates the following fields in the Session State
Session State variable name | Variable type | Comments |
---|---|---|
MSISDN |
String |
The MSISDN |
IMSI |
String |
The MT Correlation ID/IMSI used as the key for the row |
SRI4SMArgV1 |
MAPSendRoutingInfoForSMArg |
The encoded java object representing v1 SRI4SM arg, if the application context was v1 |
SRI4SMArgV2 |
MAPSendRoutingInfoForSMArg |
The encoded java object representing v2 SRI4SM arg, if the application context was v2 |
SRI4SMArgV3 |
MAPRoutingInfoForSM_Arg |
The encoded java object representing v3 SRI4SM arg, if the application context was v3 |
SRI4SMResV1 |
MAPSendRoutingInfoForSMRes |
The encoded java object representing v1 SRI4SM result, if the application context was v1 |
SRI4SMResV2 |
MAPSendRoutingInfoForSMRes |
The encoded java object representing v2 SRI4SM result, if the application context was v2 |
SRI4SMResV3 |
MAPRoutingInfoForSM_Res |
The encoded java object representing v3 SRI4SM result, if the application context was v3 |
SRI4SMResAppContext |
String |
A string of the application context name |
CorrelatedMTFSM |
boolean |
Set to true if the lookup from Cassandra returned a matching row. |
MTFSMDeliveryOrder |
DeliveryOrder |
Set to PS_ONLY when no CS routing info was present in cassandra row |
SentinelSelectionKey |
SentinelSelectionKey |
Plan Id field will be set to MTFSM_PS when no CS routing info was present in cassandra row |
SRI4SMResult |
SRI4SMResult |
Set to |
Statistics
IPSMGWFetchRoutingInfoCassandra statistics are tracked by the sentinel.ipsmgw SBB and can be found under the following parameter set in REM:
SLEE-Usage → sentinel.ipsmgw service → sentinel.ipsmgw SBB → feature → IPSMGWFetchRoutingInfoCassandra
or with rhino-stats:
"SLEE-Usage.Services.ServiceID[name=sentinel.ipsmgw,vendor=OpenCloud,version=3.1.0].SbbID[name=sentinel.ipsmgw,vendor=OpenCloud,version=3.1.0].feature.IPSMGWFetchRoutingInfoCassandra"
Name | Description |
---|---|
FetchRoutingInfoSuccess |
Incremented when a matching record is returned from Cassandra |
FetchRoutingInfoFailure |
Incremented when a matching record is not returned from Cassandra |
Configuration
The feature uses the IPSMGWRoutingInfoCassandraConfigProfileTable
profile to configure whether tracing is enabled for Cassandra queries.
Behaviour
The feature is triggered on MAP MT Forward Short Message (MT-FSM) requests. The IMSI in the MT-FSM is used as the 'mtcorrelationid' primary key field when querying Cassandra. The contents of the query result are written into session state, and used to facilitate delivery of the SMS.
If a row is not found, an UnidentifiedSubscriber error is returned to the SMSC and the feature ends.
If a row is found, the Store Routing Info Cassandra feature has written all available CS routing data to Cassandra using the schema detailed here.
If the row includes circuit switched routing information for SMS (i.e. the SRI request and response), the feature ends. If the row does not include CS routing info or the any of the CS routing info fields such as the arg or the res could not be decoded, but PS is one of the options in the current MTFSMDeliveryOrder session state field, the plan Id in the selection key is set to MTFSM_PS and the MTFSMDeliveryOrder is set to PS_ONLY
- otherwise an unidentifiedSubscriber error is sent in response to the MT-FSM.
Generate MT Correlation Id
This feature generates a correlation IMSI when responding to a SRI request. It uses the Correlation Resource Adaptor to allocate an IMSI based on the MCC and MNC.
The generated correlation IMSI is saved in session state and saved in the cassandra database by Store Routing Info Cassandra feature for further inspection when delivering a Short Message.
For quick overview see Flows for SMS delivery.
Feature cheat sheet
Feature Name | Network Operator Data | Used in PlanId(s) | Stateful or Stateless | POJO Feature or SBB Feature |
---|---|---|---|---|
IPSMGWGenerateMTCorrelationId |
Yes |
SRI4SM |
Stateless |
POJO |
Behaviour
The feature is triggered by a SRI_SM response (Version 1, 2 or 3) from the HLR. In the successful case, it extracts the MCC and MNC from the IMSI in the SRI_SM response. Once the MCC and MNC are extracted, PLMN ID Analyser Component is used to check that the PLMN ID (MCC + MNC) is configured as a home PLMN ID, then the feature requests a correlation IMSI from the Correlation Resource Adaptor, providing the PLMN ID. If the SRI_SM failed, it uses the FakeMCC
and FakeMNC
configured in the IPSMGWGenerateMTCorrelationIdConfigProfileTable
. If the Correlation RA allocates an IMSI successfully, the feature checks if the correlation IMSI is already in use by querying the Cassandra database. If the correlation IMSI is not in use, the feature stores the correlation IMSI into Session State and finishes execution. If the correlation IMSI is in use, the feature requests another correlation IMSI from the Correlation RA. The process is retried up to MaxGenerationAttempts
number of times.
An SMSC may use a correlation IMSI for some period of time after the SRI-SM transaction completes. However the correlation IMSI will be returned to the pool after a configured time period. Therefore the "in-use" check is performed by this feature. See Store Routing Info Cassandra to understand when the correlation IMSI is erased from the database.
Configuration
The feature uses the IPSMGWGenerateMTCorrelationIdConfigProfileTable
and the SIP Sentinel Configuration for its configuration.
IPSMGWGenerateMTCorrelationIdConfigProfileTable
Profile field | Variable type | Description |
---|---|---|
MaxGenerationAttempts |
int |
Number of attempts to generate the correlation IMSI |
CassandraTracing |
Boolean |
If |
FakeMCC |
String |
The fake MCC to be used when generating a fake IMSI |
FakeMNC |
String |
The fake MNC to be used when generating a fake IMSI |
The correlation IMSI pool configuration is described on the Configuring a Correlation RA entity page.
Session input and output variables
Statistics
IPSMGWGenerateMTCorrelationId statistics are tracked by the sentinel.ipsmgw SBB and can be found under the following parameter set in REM:
SLEE-Usage → sentinel.ipsmgw service → sentinel.ipsmgw SBB → feature → IPSMGWGenerateMTCorrelationId
or with rhino-stats:
"SLEE-Usage.Services.ServiceID[name=sentinel.ipsmgw,vendor=OpenCloud,version=3.1.0].SbbID[name=sentinel.ipsmgw,vendor=OpenCloud,version=3.1.0].feature.IPSMGWGenerateMTCorrelationId"
Statistic | Incremented when… |
---|---|
FoundIMSI |
could retrieve the IMSI from the SRI-SM response message |
FoundMtCorrelationId |
could generate a correlation IMSI from correlation RA |
MtCorrelationIdInUse |
the generated IMSI is already in use |
MtCorrelationIdValid |
the generated IMSI is available (not in use) and set in session state |
ErrorGeneratingMtCorrelationId |
fatal exception is raised |
Retries |
the number of attempts required to allocate a non in-use correlation IMSI, values greater than 1 a retry was needed |
Generate Message Reference
This feature increments (or creates) a row in the Cassandra cluster for the current MSISDN, to be used as the RP Message Reference, writing the value into session state.
Feature cheat sheet
Feature Name | Network Operator Data | Used in PlanId(s) | Stateful or Stateless | POJO Feature or SBB Feature |
---|---|---|---|---|
IPSMGWGenerateMessageReference |
No |
MTFSM |
Stateless |
POJO |
Prerequisite features
This feature must run after Fetch Routing Info Cassandra.
Configuration
The feature reads configuration from the Profile Table named IPSMGWGenerateMessageReferenceConfigProfileTable
. The profile name is scoped according to Sentinel Selection Key.
Attributes | Type | Meaning |
---|---|---|
ConsistencyLevel |
String |
Cassandra consistency to be applied to the queries. Valid values are |
QueryTimeoutSeconds |
int |
The number of seconds to wait for a response from Cassandra (default 10) |
MaxRetries |
int |
The number of retries due to Compare and Set failure. Default 3 |
MinRetryDelayMillis |
int |
The minimum number of milliseconds between retries due to Compare and Set failure. Default 50, minimum of zero. |
MaxRetryDelayMillis |
int |
The maximum number of milliseconds between retries due to Compare and Set failure. Default 250. |
TotalNumberOfSites |
int |
The total number of geo-redundant sites in which IPSMGW will be running (1-16). Default 1, maximum of 16. |
SiteId |
int |
The unique ID number of this site within the set of geo-redundant sites. Default 1, maximum of |
Behaviour
The feature queries the Cassandra Database using a Primary Key of the MSISDN of the Served User and the schema detailed here. The resulting value is stored into the MessageReference
session state variables for use by other features.
As multiple SMS may be delivered to the same MSISDN simultaneously, the feature uses an atomic Compare and Set (CAS) statement when creating/incrementing the message reference. The use of CAS is governed by a retry loop, so that a single failure to create/increment the message reference does not cause the message delivery to fail (as when simultaneous CAS operations execute, one operation succeeds and the others fail). The MaxRetries
, MinRetryDelayMillis
, and MaxRetryDelayMillis
ensure that the loop is bounded in number of iterations, and is able to be tuned as desired. When a CAS operation fails, a random delay (between MinRetryDelayMillis
and MaxRetryDelayMillis
) occurs before the executing thread will attempt another CAS operation. A value of zero for MinRetryDelayMillis
means that the thread will immediately attempt the next CAS operation.
If IPSMGW is running across multiple geo-redundant sites, then TotalNumberOfSites
and SiteId
are used to partition the generated message reference numbers into non-overlapping ranges. Within a single site, the above CAS operation will be used to ensure unique message reference numbers. Between different sites, the uniqueness depends on the SiteId
being unique amongst the total number of sites and the TotalNumberOfSites
accurately reflecting how many sites there are in total. The feature will then constrain its generated message reference numbers to the range calculated for that particular site.
The feature has Configuration controls around the Compare and Set loop.
If the feature fails to generate the message reference for any reason, it resumes the SMSC leg and sends back an error response, while flagging the failure in session state.
Statistics
IPSMGWGenerateMessageReference statistics are tracked by the sentinel.ipsmgw SBB and can be found under the following parameter set in REM:
SLEE-Usage → sentinel.ipsmgw service → sentinel.ipsmgw SBB → feature → IPSMGWGenerateMessageReference
or with rhino-stats:
"SLEE-Usage.Services.ServiceID[name=sentinel.ipsmgw,vendor=OpenCloud,version=3.1.0].SbbID[name=sentinel.ipsmgw,vendor=OpenCloud,version=3.1.0].feature.IPSMGWGenerateMessageReference"
Statistic | Incremented when… |
---|---|
FailedToExecuteCassandraStatement |
A cassandra query could not be executed successfully - could be caused by the RA or the Database - turn on finer tracing for details |
InsertFailed |
This is not a cassandra exception as in the case of FailedToExecuteCassandraStatement - instead it implies that the insert was not applied, probably due to the row already existing |
UpdateFailed |
This implies that the UPDATE failed, either due to the CAS condition failing (ie the existing value was not as expected, implying that another session had already updated the field, or the row having already been removed since the last read) |
RetriesExhausted |
The configured number of compare and set retries has been reached without successfully setting the message reference counter in cassandra |
Retries |
The number of compare and set re-attempts |
NoRowsReturned |
Even after successfully incrementing the counter, no value could be retrieved - this could only occur if the Database was modified |
Success |
The message reference counter was successfully incremented and retrieved from Cassandra |
Generate SRI Result
This feature generates a response to a SRI for SM request when the system is configured to attempt PS delivery only.
Feature cheat sheet
Feature Name | Network Operator Data | Used in PlanId(s) | Stateful or Stateless | POJO Feature or SBB Feature |
---|---|---|---|---|
IPSMGWGenerateSRIResult |
Yes |
MTFSM |
Stateless |
POJO |
Session Input Variables
The IPSMGWGenerateSRIResult feature reads the following fields from Session State:
Field Name | Field Type | Comments |
---|---|---|
SentinelSelectionKey |
SentinelSelectionKey |
Used to load configuration. |
MTCorrelatedId |
String |
Generated correlation IMSI, provided to the SMSC in the generated SRI for SM response. |
IsSMSOverIPRegistered |
boolean |
Used to determine whether the subscriber is IMS registered. |
Configuration
This feature depends on configuration from the IP-SM-GW shared configuration profile table.
Specifically, it reads these fields:
Field Name | Comments |
---|---|
DeliveryOrder |
Used to enforce that the feature only runs for PS only delivery. |
SentinelIPSMGWAddress |
Used as the MSC number in generated responses. |
See the Shared Configuration Profile page for additional information about these fields.
Feature Statistics
IPSMGWGenerateSRIResult statistics are tracked by the sentinel.ipsmgw SBB and can be found under the following parameter set in REM:
SLEE-Usage → sentinel.ipsmgw service → sentinel.ipsmgw SBB → feature → IPSMGWGenerateSRIResult
or with rhino-stats:
"SLEE-Usage.Services.ServiceID[name=sentinel.ipsmgw,vendor=OpenCloud,version=3.1.0].SbbID[name=sentinel.ipsmgw,vendor=OpenCloud,version=3.1.0].feature.IPSMGWGenerateSRIResult"
Statistic | Type | Description |
---|---|---|
Started |
Counter |
Incremented when the feature is invoked. |
FailedToStart |
Counter |
Incremented when Sentinel encounters an error while attempting to start the feature. |
IssuedWarning |
Counter |
Incremented when a non-fatal problem is encountered and the feature issues a warning. |
FailedDuringExecution |
Counter |
Incremented when a fatal problem is encountered and the feature cannot execute correctly. |
TimedOut |
Counter |
Incremented when the feature takes too long to complete and Sentinel aborts execution. |
FailedToDetermineMTCorrelatedId |
Counter |
Incremented when the feature cannot find a correlation IMSI in session state. |
IgnoringTrigger |
Counter |
Incremented when the feature is invoked on a trigger that is not a SRI for SM request. |
GeneratedSuccessResult |
Counter |
Incremented when the feature generates a success response for the SRI for SM request. |
GeneratedAbsentSubscriberError |
Counter |
Incremented when the feature generates an absent subscriber response for the SRI for SM request. |
GeneratedSystemFailureError |
Counter |
Incremented when the feature generates a system failure error response for the SRI for SM request. |
Behaviour
The feature will be invoked on receipt of a SRI for SM request from the SMSC. Its purpose is to generate a SRI for SM response towards the SMSC when it is not necessary to consult the HLR for routing information (i.e. The IP-SM-GW is configured for PS delivery only).
When invoked it will check the IMS registration state for the subscriber (as determined by the Registration Lookup From Cassandra feature).
If the subscriber is IMS registered, the feature will generate and send an SRI for SM response that is appropriate for the MAP application context used by the request. The response will identify the IP-SM-GW as the MSC for the subscriber to the SMSC, and provide the correlation IMSI for the SMSC to use when delivering messages. The correlation IMSI is generated by the Generate MT Correlation Id feature.
If the subscriber is not IMS registered will generate and send an Absent Subscriber error instead.
If for any reason the IP-SM-GW fails to generate a correlation IMSI, then the feature will generate and send a MAP System Failure error.
PS Delivery
This feature delivers an SMS encapsulated in SIP (SMS Over IP) to the UE
Feature cheat sheet
Feature Name | Network Operator Data | Used in PlanId(s) | Stateful or Stateless | POJO Feature or SBB Feature |
---|---|---|---|---|
IPSMGWPSDelivery |
Yes |
MTFSM_PS,MTFSM_PS_CS,MTFSM_CS_PS |
Stateless |
POJO |
Statistics
IPSMGWPSDelivery statistics are tracked by the sentinel.ipsmgw SBB and can be found under the following parameter set in REM:
SLEE-Usage → sentinel.ipsmgw service → sentinel.ipsmgw SBB → feature → IPSMGWPSDelivery
or with rhino-stats:
"SLEE-Usage.Services.ServiceID[name=sentinel.ipsmgw,vendor=OpenCloud,version=3.1.0].SbbID[name=sentinel.ipsmgw,vendor=OpenCloud,version=3.1.0].feature.IPSMGWPSDelivery"
Name | Description |
---|---|
SentMessage |
Incremented when a SIP MESSAGE containig RP-Message is sent to the UE |
DeliverySucceeded |
Incremented when a delivery report indicating success is received |
DeliveryFailed |
Incremented when any 3xx or greater response is received for the SIP MESSAGE or when a delivery report indicating failure is received |
DeliveryTimedOut |
Incremented when the timer that is armed on sending the SIP MESSAGE gets fired |
NotAttemptedCreditLimitReached |
Incremented when a CreditLimitReached Direct Debit CCA is received. The PS Delivery attempt is aborted, with an Sm-DeliveryFailure sent back to the SMSC |
NotAttemptedChargingFailure |
Incremented when a general charging error occurs. The PS Delivery attempt is aborted, with an Sm-DeliveryFailure sent back to the SMSC |
SubscriptionFailed |
Incremented when an attempt to subscribe to UEReachabilityForIP notifications fails |
SentReportSMDeliveryStatus |
Incremented when a ReportSMDeliveryStatus message is sent to the UE |
FailedToSendReportSMDeliveryStatus |
Incremented when there was an error trying to send a ReportSMDeliveryStatus message |
ReportSMSucceeded |
Incremented when a ReportSMDeliveryStatus success response is received |
ReportSMFailed |
Incremented when a ReportSMDeliveryStatus error response is received |
ReportSMSuppressed |
Incremented when a ReportSMDeliveryStatus error response is suppressed |
Configuration
The IPSMGWPSDelivery feature configuration is scoped according to a Sentinel Selection Key. The IPSMGWPSDelivery feature refers to three Profile Tables for configuration.
The first Profile Table is Shared Configuration Profile
. The following attributes are used:
Attributes | Type | Meaning |
---|---|---|
ICSCFURI |
String |
The I-CSCF SIP URI that will be used to route outbound SIP MESSAGE requests (see SIP Transports and Routing) |
SipTransport |
String |
The SIP transport for the IPSMGW’s own SIP URI, used in the |
SubscribeToUEReachabilityForIP |
Boolean |
If true, request UEReachabilityForIP notifications from the HSS on certain PS Delivery failures. |
DeliveryOrder |
Enum |
If CS Delivery will run after PS Delivery, there is no need to send error report to SMSC on PS delivery failure |
UseMsisdnAsHlrAddress |
Boolean |
Controls whether to address the outbound HLR leg using a GT address formed from the subscriber MSISDN, instead of using the configured |
ChargingOptions |
String[] |
If this array contains the value |
SuppressHLRInteraction |
boolean |
If true, no MAP messages will be sent to the HLR. Can only be set to true when DeliveryOrder is PS_ONLY. For more information, refer to Suppression of HLR Interaction |
The second Profile Table is IPSMGWPSDeliveryConfigProfileTable
. The following attributes are used:
Attributes | Type | Meaning |
---|---|---|
FallbackTimer |
int |
Time in milliseconds to wait for a response during PS Delivery before setting 'PSDeliveryStatus' to FAILED |
RPErrorFallbackAvoidanceCodes |
int[] |
A list of error codes that if matched from the RP-ERROR will stop a CS fallback |
The third Profile Table (IPSMGWPSDeliveryPerNodeURIConfigTable
) holds node-specific feature configuration. The following attributes are used:
Attributes | Type | Meaning |
---|---|---|
NodeURI |
String |
The SIP Local URI for this node to use when sending the MESSAGE |
MAP Application Contexts
The feature can be triggered by any of the following MAP Application Contexts: shortMsgMT_RelayContext_v3_ac
shortMsgMT_RelayContext_v2_ac
shortMsgMT_RelayContext_v1_ac
Behaviour
The feature is triggered upon receipt of a mt_ForwardSM in any of the above three MAP Application Contexts.
After validating configuration and session state inputs, it then takes the ForwardSM argument and creates an RpDATA that it can send in a SIP MESSAGE to the ICSCF
The SIP MESSAGE is created as follows:
If a short message is received from the SMS-GMSC, the IP-SM-GW shall extract the IMSI of the SM-over-IP receiver from the received message. Then the IP-SM-GW shall send a SIP MESSAGE request with the following information:
a) the Request-URI, which shall contain a public user identity of the SM-over-IP receiver associated with the received IMSI;
b) the Accept-Contact header, which shall contain a "+g.3gpp.smsip" parameter and the "explicit" and "require" tags according to RFC 3841 [17];
c) the Request-Disposition header which shall contain the "no-fork" directive;
d) the P-Asserted-Identity header which shall contain the SIP URI of the IP-SM-GW;
e) the Content-Type header which shall contain "application/vnd.3gpp.sms"; and
f) the body of the request which shall contain an RP-DATA message as defined in 3GPP TS 24.011 [8], including the SMS headers and the SMS user information encoded as specified in 3GPP TS 23.040 [3].
For example flows, see MT Delivery Flows
The IPSMGWPSDelivery feature arms a service timer (with the value of FallbackTimer
attribute in the IPSMGWPSDeliveryConfigProfileTable) when it sends the SIP MESSAGE. If this timer expires, then PS Delivery has taken too long and the PSDeliveryStatus session state field is set to FAILED (default is NOT_ATTEMPTED.)
The following tables explains the behaviour during MT PS delivery.
PS_ONLY or CS_THEN_PS
This section describes the behaviour when the DeliveryOrder
attribute in the Shared Configuration Profile
is set to PS_ONLY
or CS_THEN_PS
.
For a PS delivery:
If | Then | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Charging is performed and returns a failure |
Error returned to SMSC in MT-FSM response |
||||||||||||
Response received from UE is a 408 or 410, or no response received from UE before the FallBackTimer expires |
Error returned to SMSC in MT-FSM response, IP-SM-GW subscribes to receive UEReachabilityForIP notifications using stored MSISDN, IP-SM-GW sends a MAP Report SM Delivery Status to the HLR |
||||||||||||
Response received from UE is other code that is not a 2xx (e.g. not 202 or 200) |
Error returned to SMSC in MT-FSM response |
||||||||||||
Response received from UE is a 2xx |
|
PS_THEN_CS
This section describes the behaviour when the DeliveryOrder
attribute in the Shared Configuration Profile
is set to PS_THEN_CS
. In this mode, PS Delivery may not necessarily respond to the SMSC itself, instead falling back to CS Delivery.
For a PS delivery:
If | Then | ||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Charging is performed and returns a failure |
Error returned to SMSC in MT-FSM response |
||||||||||||||||||
No Response received from UE before the FallBackTimer expires |
CS Fallback initiated, IP-SM-GW subscribes to receive a UEReachabilityForIP notification using the stored MSISDN |
||||||||||||||||||
Response received from UE is not a 2xx (e.g. not 202 or 200) |
CS Fallback initiated, IP-SM-GW may subscribe to receive a UEReachabilityForIP notification using the stored MSISDN |
||||||||||||||||||
Response received from UE is a 2xx |
|
Requesting a UE Reachability for IP Notification
This feature may request a UE Reachability for IP Notification from the HSS, using Diameter Sh’s SubscribeNotificationRequest
operation (through the Sh Cache Microservice). This operation is only sent to the HSS if the SubscribeToUEReachabilityForIP configuration flag is set to true and one of the following occurs:
-
the SIP Message Request sent towards the UE is responded to with a 408 (Request Timeout) or 410 (Gone) error response, or
-
an RP-ACK or RP-ERROR is not received from the UE within a guard time period
The guard time value is the FallBackTimer. The Sh SubscribeNotificationRequest operation is sent with the MSISDN as the access key, and the One Time Notification flag set.
Session state inputs and outputs
Inputs
Name | Type | Format | Description | Behaviour if null/invalid |
---|---|---|---|---|
SentinelSelectionKey |
com.opencloud.sentinel.common.SentinelSelectionKey |
selection key (for example, |
For selecting configuration data and updating network operator field |
Report featureCannotStart, featureHasFinished |
MSISDN |
String |
The MSISDN to use in the subscription-notification and ReportSMDeliveryStatus operations, and to use for GT routing if configured |
Unable to send subscription-notification and ReportSMDeliveryStatus messages, and to route on GT if configured |
|
IsSMSOverIPRegistered |
boolean |
N/A |
True if the user is logged in to the IMS - feature only runs if logged in |
|
MTFSMDeliveryOrder |
com.opencloud.sentinel.ipsmgw.shared.config.profile.DeliveryOrder |
One of |
Current DeliveryOrder based on configuration and available routing info, correpsonding to current selection key plan Id. |
Set PSDeliveryStatus to FAILED and report featureHasFinished |
RegistrationRecords |
List of com.opencloud.sentinel.state.RegistrationRecord |
RegistrationRecords for the user - the default public ID is extracted from the first record and used as the RequestURI |
Report featureCannotStart, featureHasFinished |
|
SRI4SMArgV1, SRI4SMArgV2, SRI4SMArgV3 |
com.opencloud.slee.resources .cgin.map.MAPSendRoutingInfoForSMArg, com.opencloud.slee.resources .cgin.map.MAPRoutingInfoForSM_Arg |
The SendRoutingInfoForSM Arg received from the SMSC, used to populate the service centre address in a Report SM Delivery Status |
Use the IP-SM-GW address as the service centre address |
Outputs
Name | Type | Description |
---|---|---|
PSDeliveryStatus |
Enum |
Values are NOT_ATTEMPTED, FAILED, SUCCEEDED. Indicates the state of PS Delivery |
FallbackAllowed |
boolean |
True if the RP-Data Deliver MESSAGE received a SIP error response, or no RP-Ack MESSAGE was received, or if the delivery report didn’t contain RP Data, or if an RP-Error was received and its cause code was not a configured RPErrorFallbackAvoidanceCodes value. |
RP Cause Mappings
Any values not in the table are still valid as RPErrorFallbackAvoidanceCodes
but it is unlikely they will appear in the RP-ERROR.
Cause | Value |
---|---|
UNASSIGNED_NUMBER |
1 |
OPERATOR_DETERMINED_BARRING |
8 |
CALL_BARRED |
10 |
RESERVED |
11 |
SHORT_MESSAGE_TRANSFER_REJECTED |
21 |
MEMORY_CAPACITY_EXCEEDED |
22 |
DESTINATION_OUT_OF_ORDER |
27 |
UNIDENTIFIED_SUBSCRIBER |
28 |
FACILITY_REJECTED |
29 |
UNKNOWN_SUBSCRIBER |
30 |
NETWORK_OUT_OF_ORDER |
38 |
TEMPORARY_FAILURE |
41 |
CONGESTION |
42 |
RESOURCES_UNAVAILABLE |
47 |
REQUESTED_FACILITY_NOT_SUBSCRIBED |
50 |
REQUESTED_FACILITY_NOT_IMPLEMENTED |
69 |
INVALID_SHORT_MESSAGE_REFERENCE_VALUE |
81 |
INVALID_MESSAGE |
95 |
INVALID_MANDATORY_INFORMATION |
96 |
MESSAGE_TYPE_NONEXISTENT_OR_NOT_IMPLEMENTED |
97 |
MESSAGE_NOT_COMPATIBLE_WITH_SHORT_MESSAGE_PROTOCOL_STATE |
98 |
INFORMATION_ELEMENT_NONEXISTENT_OR_NOT_IMPLEMENTED |
99 |
PROTOCOL_ERROR |
111 |
INTERWORKING |
127 |
Registration Lookup From Cassandra
This feature reads Third Party Registration information stored in the Cassandra Database, and writes it into session state. Information is read during MT ForwardSM processing. It reads the Third Party Registration information via the Cassandra CQL RA. For more information refer to Cassandra Storage.
Feature cheat sheet
Feature Name | Network Operator Data | Used in PlanId(s) | Stateful or Stateless | POJO Feature or SBB Feature |
---|---|---|---|---|
IPSMGWRegistrationLookupFromCassandra |
No |
MTFSM_PS,MTFSM_PS_CS,MTFSM_CS_PS |
Stateless |
POJO |
Prerequisite features
These features must run after Fetch Routing Info Cassandra.
Session input and output variables
Session input variables
Session State variable name | Variable type |
---|---|
MSISDN |
String |
|
String |
Session output variables
Session State variable name | Variable type | Comments |
---|---|---|
RegistrationRecords |
List<RegistrationRecord> |
The list of registration records for the subscriber |
IsSMSOverIPRegistered |
boolean |
True, if the feature found a valid record in the database and if the |
Statistics
IPSMGWRegistrationLookupFromCassandra statistics are tracked by the sentinel.ipsmgw SBB and can be found under the following parameter set in REM:
SLEE-Usage → sentinel.ipsmgw service → sentinel.ipsmgw SBB → feature → IPSMGWRegistrationLookupFromCassandra
or with rhino-stats:
"SLEE-Usage.Services.ServiceID[name=sentinel.ipsmgw,vendor=OpenCloud,version=3.1.0].SbbID[name=sentinel.ipsmgw,vendor=OpenCloud,version=3.1.0].feature.IPSMGWRegistrationLookupFromCassandra"
Statistic | Incremented when… |
---|---|
NoSubscriberSpecified |
the MSISDN is empty |
RegistrationRetrieveSuccess |
Registration found in the database |
RegistrationRetrieveFail |
an exception occurs in cassandra |
CassandraQueried |
the database is queried |
SubscriberNotRegistered |
could not find an active subscriber in the database |
SupportSMSIP |
found a valid record in the database and the |
SubscriberNotActive |
found a valid subscriber in the database but its status is not active. |
Behaviour
The feature queries the Cassandra Database using a Primary Key of the IMS Public Identity of the Served User constructed from the MSISDN provided by the SRI request. It creates a TEL URI
using the MSISDN, and if can’t find the subscriber in the database it creates a SIP URI
using the domain specified in SentinelDestinationDomain
from Shared Configuration Profile and query the database again.
User logged in
The RegistrationRecords
session state field is set to a List
of RegistrationRecord
if the indication g.3gpp.smsip
is present in the Contacts
header. Each element in the list indicates a device, with public and private IDs, that the subscriber is registered on. If the subscriber is registered on only one device, there is only one element in the list. If the subscriber is simultaneously registered on (say) four devices, there will be four elements in the list.
User not logged in
If the user is not logged in, the feature finishes execution without modifying any state.
Support for SMS over IP
If, during the registration process, the subscriber indicates if supports SMS over IP
, then the feature sets the field IsSMSOverIPRegistered
to true. The presence of the string g.3gpp.smsip
in the Contacts header indicates that the subscriber supports SMS over IP. In this case the IPSMGW will try to forward the message to the PS network.
Store Routing Info Cassandra
This feature stores SMS routing information in Cassandra. The stored data includes additional correlation information.
Feature Cheat Sheet
Feature Name | Network Operator Data | Used in PlanId(s) | Stateful or Stateless | POJO Feature or SBB Feature |
---|---|---|---|---|
IPSMGWStoreRoutingInfoCassandra |
Yes |
SRI4SM, SRI4SM_PS_ONLY, MTFSM_PS, MTFSM_CS, MTFSM_CS_PS, MTFSM_PS_CS |
Stateless |
POJO |
Feature Parameters
This feature can operate with two parameters - 'Store' or 'Refresh'. For details, please refer to Behaviour.
Session Input Variables
The IPSMGWStoreRoutingInfoCassandra feature reads the following fields from Session State:
Field Name | Field Type | Comments |
---|---|---|
SentinelSelectionKey |
SentinelSelectionKey |
Used to load configuration. |
MTCorrelatedId |
String |
Generated correlation IMSI. |
IsSMSOverIPRegistered |
boolean |
Used to determine whether the subscriber is IMS registered. |
MTFSMDeliveryOrder |
DeliveryOrder |
Used to determine whether PS only delivery is being used. |
IMSI |
String |
The subscriber’s IMSI. |
MSISDN |
String |
The subscriber’s MSISDN. |
MtForwardSMIncomingLeg |
String |
Name of the leg on which an MT-FSM request was received. |
SRI4SMArgV1 |
MAPSendRoutingInfoForSMArg |
The encoded java object representing v1 SRI4SM arg, if the application context was v1. |
SRI4SMArgV2 |
MAPSendRoutingInfoForSMArg |
The encoded java object representing v2 SRI4SM arg, if the application context was v2. |
SRI4SMArgV3 |
MAPRoutingInfoForSM_Arg |
The encoded java object representing v3 SRI4SM arg, if the application context was v3. |
SRI4SMResV1 |
MAPSendRoutingInfoForSMRes |
The encoded java object representing v1 SRI4SM result, if the application context was v1. |
SRI4SMResV2 |
MAPSendRoutingInfoForSMRes |
The encoded java object representing v2 SRI4SM result, if the application context was v2. |
SRI4SMResV3 |
MAPRoutingInfoForSM_Res |
The encoded java object representing v3 SRI4SM result, if the application context was v3. |
SRI4SMResAppContext |
String |
A string of the application context name. |
UUID |
UUID |
UUID used when refreshing data in cassandra, |
Statistics
IPSMGWStoreRoutingInfoCassandra statistics are tracked by the sentinel.ipsmgw SBB and can be found under the following parameter set in REM:
SLEE-Usage → sentinel.ipsmgw service → sentinel.ipsmgw SBB → feature → IPSMGWStoreRoutingInfoCassandra
or with rhino-stats:
"SLEE-Usage.Services.ServiceID[name=sentinel.ipsmgw,vendor=OpenCloud,version=3.1.0].SbbID[name=sentinel.ipsmgw,vendor=OpenCloud,version=3.1.0].feature.IPSMGWStoreRoutingInfoCassandra"
Statistic | Type | Description |
---|---|---|
Started |
Counter |
Incremented when the feature is invoked. |
FailedToStart |
Counter |
Incremented when Sentinel encounters an error while attempting to start the feature. |
IssuedWarning |
Counter |
Incremented when a non-fatal problem is encountered and the feature issues a warning. |
FailedDuringExecution |
Counter |
Incremented when a fatal problem is encountered and the feature cannot execute correctly. |
TimedOut |
Counter |
Incremented when the feature takes too long to complete and Sentinel aborts execution. |
StartedStore |
Counter |
Incremented when the feature is triggered with a mode of 'Store'. |
StartedRefresh |
Counter |
Incremented when the feature is triggered with a mode of 'Refresh'. |
TriggerOpenRequest |
Counter |
Incremented when the feature is triggered on a DialogOpenRequestTcapMessage. |
TriggerTCOperation |
Counter |
Incremented when the feature is triggered on a TCOperationTcapMessage. |
TriggerTCEnd |
Counter |
Deprecated and not used. |
TriggerSipResponse |
Counter |
Deprecated and not used. |
ParsingSendRoutingInfoForSMArgV1 |
Counter |
Incremented when the feature attempts to parse a MAP v1 MAPSendRoutingInfoForSMArg. |
ParsingSendRoutingInfoForSMArgV2 |
Counter |
Incremented when the feature attempts to parse a MAP v2 MAPSendRoutingInfoForSMArg. |
ParsingSendRoutingInfoForSMArgV3 |
Counter |
Incremented when the feature attempts to parse a MAP v3 MAPRoutingInfoForSM_Arg. |
ParsingSendRoutingInfoForSMResV1 |
Counter |
Incremented when the feature attempts to parse a MAP v1 MAPSendRoutingInfoForSMRes. |
ParsingSendRoutingInfoForSMResV2 |
Counter |
Incremented when the feature attempts to parse a MAP v2 MAPSendRoutingInfoForSMRes. |
ParsingSendRoutingInfoForSMResV3 |
Counter |
Incremented when the feature attempts to parse a MAP v3 MAPRoutingInfoForSM_Res. |
RefreshingData |
Counter |
Incremented when the feature refreshes data. |
RefreshingRefreshingDataSkippedDueErrorMessage |
Counter |
Incremented when the feature skips refreshing the data due to receiving an error message. |
DataStoreError |
Counter |
Incremented when data is not successfully stored to Cassandra. |
DataStoreSuccess |
Counter |
Incremented when data is successfully stored in Cassandra. |
Configuration
The feature uses the IPSMGWRoutingInfoCassandraConfigProfileTable
profile to configure the Cassandra attribute time-to-live (TTL), and whether tracing is enabled for Cassandra queries. The following attributes are used:
Attributes | Type | Meaning |
---|---|---|
CassandraTTL |
int |
Cassandra’s |
CassandraTracing |
boolean |
If |
Additionally, the feature uses the following field on the IP-SM-GW shared configuration profile table:
Field Name | Comments |
---|---|
SentinelIPSMGWAddress |
Used as the MSC number when generating translated responses. |
See the Shared Configuration Profile page for additional information about this field.
Behaviour
The feature stores the routing information for SMS into the Cassandra Database using the schema detailed here. This includes the SRI for SM request and response content. It can operate in two modes - 'Store' or 'Refresh'.
When storing or refreshing data in Cassandra, the primary key is formatted as an IMSI, and its value is read from Session State. If suitable primary key information is not available (for example the Generate MT Correlation Id feature was unable to allocate a correlation IMSI), or there is a failure to write the routing information into Cassandra, an error response to the SRI for SM is sent.
This feature is closely related to the Fetch Routing Info Cassandra feature.
Store Mode
'Store' mode is triggered on incoming SRI for SM Requests and responses.
On a successful SRI response, the feature encodes it and its associated request, and writes them into the Cassandra DB using the generated MT Correlation IMSI as the primary key. Along with the encoded request and response, the true IMSI, the MSISDN, and the SAS universal identifier are also written into the Cassandra DB.
When the feature is triggered by an SRI for SM error result, it will attempt to write a similar entry to the Cassandra DB, omitting the encoded response and the true IMSI. If the write is successful, it will replace the proxied error with a success response including the correlation IMSI. When this entry is read by FetchRoutingInfo during MT-FSM handling, it indicates that CS delivery is not possible, but PS delivery may be an option. The row is stored with a configurable TTL, so no manual cleanup process is required.
On a request, if the delivery mode is PS only or PS then CS, the feature will look for a response generated by the Generate SRI Result feature. If it finds a successful SRI4SM result, it will process it in the same way as it would process a normal response trigger, except that the true IMSI will be omitted from stored data. If no generated response is found, a generated error response is found, or the delivery mode is not PS only or PS then CS, then the feature will take no further action.
Refresh Mode
'Refresh' mode is triggered on indication of successful delivery of an SMS message (either via SIP encapsulated SMS over IP, or via a MAP MT Forward SM ACK). The successful delivery of an SMS indicates that the routing info remains valid and should not time out, so it is refreshed in Cassandra. This ensures that a batch of SMS for the same IMSI within the Time To Live period are correlated together. The feature uses the fields stored in session state by the IPSMGWFetchRoutingInfoCassandra feature and re-stores them in Cassandra.
Registrar Features
These features relate to Third Party Registration
Feature | What it does |
---|---|
sets a session state field based on the presence of the “+g.3gpp.smsip” parameter in first party SIP Register request Contact headers and the subscriber MSISDN session state field. |
|
sends a MAP AnyTimeModification request to HLR to set the IP-SM-GW address and set active flag to true when a user registers. |
|
records registration requests in Cassandra to keep track of which site a user last registered at. |
ATM Registration
This feature sends a MAP AnyTimeModification request to HLR to set the IP-SM-GW address and set active flag to true when a user registers.
Feature cheat sheet
Feature Name | Network Operator Data | Used in PlanId(s) | Stateful or Stateless | POJO Feature or SBB Feature |
---|---|---|---|---|
IPSMGWATMRegistration |
No |
register,de_register |
Stateless |
SBB |
Statistics
ATMRegistration statistics are tracked by the sentinel.ipsmgw SBB and can be found under the following parameter set in REM:
SLEE-Usage → sentinel.ipsmgw service → sentinel.ipsmgw SBB → feature → IPSMGWATMRegistration
or with rhino-stats:
"SLEE-Usage.Services.ServiceID[name=sentinel.ipsmgw,vendor=OpenCloud,version=3.1.0].SbbID[name=sentinel.ipsmgw,vendor=OpenCloud,version=3.1.0].feature.IPSMGWATMRegistration"
Name | Description |
---|---|
Started |
Incremented each time the feature runs |
Failed |
Incremented when a fatal error occurs during feature execution |
RequestSent |
Incremented when ATM request is sent to HLR |
RequestSuccessful |
Incremented when a ATM non-error response is received from HLR |
RequestFailed |
Incremented when a ATM error response is received from HLR |
RequestSuppressed |
Incremented when ATM request is suppressed |
Configuration
The feature is configured with configuration scoped according to a Sentinel Selection Key. The Profile Table used to hold feature configuration is Shared Configuration Profile
. The following attributes are available
Attributes | Type | Meaning |
---|---|---|
HlrAddress |
String |
Address of the HLR to request the MSRN from, used when establishing the MAP dialog if |
UseMsisdnAsHlrAddress |
boolean |
Controls whether to address the outbound HLR leg using a GT address formed from the subscriber MSISDN, instead of using the configured |
SentinelOriginatingAddress |
String |
Address of Sentinel used when establishing the MAP dialog |
SentinelIPSMGWAddress |
String |
The IP-SM-GW address that the feature will include it in MAP AnyTimeModification request to send to HLR |
InvokeTimeout |
int |
The timeout in milliseconds for the response from HLR. Used in the TCAP layer for the invoke timeout. Default is 5000 |
SuppressHLRInteraction |
boolean |
If true, no MAP messages will be sent to the HLR. Can only be set to true when DeliveryOrder is PS_ONLY. For more information, refer to Suppression of HLR Interaction |
Using MSISDN as HLR Address
The ATM Registration feature can optionally address the HLR leg using a GT address formed from the inbound subscriber MSISDN, as opposed to using the destination addresses configured in the IPSMGWMapProxyConfigProfileTable
profile table described above.
This behaviour can be enabled or disabled by setting the UseMsisdnAsHlrAddress
attribute in the Shared Configuration Profile
.
Behaviour
The feature is triggered upon Initial Registration, and De-Registration. It is not triggered on registration refresh.
On initial registration, this feature sends a MAP AnyTimeModification request to the HLR to set IP-SM-GW address and the IP-SM-GW active flag. The IP-SM-GW address is configured in a configuration profile.
When a user de-registers, the feature sends a MAP AnyTimeModification request to the HLR to clear the IP-SM-GW Active flag.
The feature can be inhibited if the IPSMGW is configured to suppress HLR Interaction (see Suppression of HLR Interaction)
Determine SMS Registration
This feature sets a session state field based on the presence of the “+g.3gpp.smsip” parameter in first party SIP Register request Contact headers and the subscriber MSISDN session state field.
Feature cheat sheet
Feature Name | Network Operator Data | Used in PlanId(s) | Stateful or Stateless | POJO Feature or SBB Feature |
---|---|---|---|---|
IPSMGWDetermineSMSRegistration |
No |
Any |
Stateless |
POJO |
Session output variables
Session State variable name | Variable type | Comments |
---|---|---|
isSmsip |
boolean |
True if the feature finds the “+g.3gpp.smsip” parameter in the contact headers. |
MSISDN |
String |
The MSISDN retrieved from the REGISTER message. |
Statistics
DetermineSMSRegistration statistics are tracked by the sentinel.ipsmgw SBB and can be found under the following parameter set in REM:
SLEE-Usage → sentinel.ipsmgw service → sentinel.ipsmgw SBB → feature → IPSMGWDetermineSMSRegistration
or with rhino-stats:
"SLEE-Usage.Services.ServiceID[name=sentinel.ipsmgw,vendor=OpenCloud,version=3.1.0].SbbID[name=sentinel.ipsmgw,vendor=OpenCloud,version=3.1.0].feature.IPSMGWDetermineSMSRegistration"
Name | Description |
---|---|
isSmsip |
Incremented when the feature has set the isSmsip Session State field to true |
incrementFailedToDetermineMSISDN |
Incremented if an SMS over IP session and unable to determine the subscriber MSISDN. |
Behaviour
This feature checks incoming SMS Register messages for the presence of the +g.3gpp.smsip
parameter in the contact headers of the message. If the parameter is present, the 'isSmsip' session state field is set to true. In all other cases the field defaults to false. If is an SMS over IP session, this feature also extracts a valid phone number from the IMPUs of the incoming REGISTER request and sets the MSISDN session state field.
Registration Ownership Tracking
This feature records registration requests in Cassandra to keep track of which site a user last registered at.
Feature cheat sheet
Feature Name | Network Operator Data | Used in PlanId(s) | Stateful or Stateless | POJO Feature or SBB Feature |
---|---|---|---|---|
IPSMGWRegistrationTrackingCassandra |
Yes |
register,de_register |
Stateless |
POJO |
Session Input variables
The feature reads the following fields in Session State
Session State variable name | Variable type | Comments |
---|---|---|
MSISDN |
String |
The MSISDN of the subscriber issuing the (de-)registration request. Used as part of the primary key in the registration record in Cassandra. |
networkInitiatedDeRegistration |
boolean |
Used to determine if a de-registration request was user or network initiated. Network-initiated de-registration requests for users registered most recently at a different site will result is the |
encapsulatedRegisterResponse |
javax.sip.message.Response |
Used to extract the max expires header value for the TTL value when recording the registration record in Cassandra. |
ATMRegistrationSuccessful |
boolean |
Set by the ATM Registration feature to indicate if the ATM registration was successful or not. Used during registration to conditionally write an ownership record only if the ATM registration was successful. |
Session output variables
Session State variable name | Variable type | Comments |
---|---|---|
skipATMRegistration |
boolean |
True if the |
Statistics
IPSMGWRegistrationTrackingCassandra statistics are tracked by the sentinel.ipsmgw SBB and can be found under the following parameter set in REM:
SLEE-Usage → sentinel.ipsmgw service → sentinel.ipsmgw SBB → feature → IPSMGWRegistrationTrackingCassandra
or with rhino-stats:
"SLEE-Usage.Services.ServiceID[name=sentinel.ipsmgw,vendor=OpenCloud,version=3.1.0].SbbID[name=sentinel.ipsmgw,vendor=OpenCloud,version=3.1.0].feature.IPSMGWRegistrationTrackingCassandra"
Name | Type | Description |
---|---|---|
Started |
Counter |
Incremented when the feature is triggered. |
FailedToStart |
Counter |
Incremented when the feature fails to start. |
FailedDuringExecution |
Counter |
Incremented when the feature fails while executing. |
IssuedWarning |
Counter |
Incremented when the feature issues a warning. |
TimedOut |
Counter |
Incremented when the feature times out during execution. |
DataStoreError |
Counter |
Incremented when the feature is unable to write a registration record to Cassandra. |
DataStoreSuccess |
Counter |
Incremented when the feature successfully writes a registration record to Cassandra. |
DataReadError |
Counter |
Incremented when the feature is unable to read the registration records from Cassandra. |
WriteConsistencyFallback |
Counter |
Incremented when the feature falls back from QUORUM to LOCAL_QUORUM consistency for a write to Cassandra. |
ReadConsistencyFallback |
Counter |
Incremented when the feature falls back from QUORUM to LOCAL_QUORUM consistency for a read from Cassandra. |
MissingRegistrationRecord |
Counter |
Incremented when the feature is unable to find any registration record for the subscriber during a de-register request. |
ReadResponseLatency |
Sample |
Sample statistic of the RTT for Cassandra read requests. |
WriteResponseLatency |
Sample |
Sample statistic of the RTT for Cassandra write requests. |
Configuration
The feature’s configuration is scoped by the Sentinel Selection Key. The Profile Table used to hold feature configuration is IPSMGWRegistrationTrackingCassandraConfigProfileTable
. The following attributes are available:
Attributes | Type | Meaning |
---|---|---|
CassandraTTL |
int |
The base TTL to use for the registration record in Cassandra (the max expires header value will be added to this) |
CassandraTracing |
boolean |
Controls whether tracing is enabled for Cassandra queries |
Behaviour
The feature is triggered upon Initial Registration, and De-Registration.
On initial registration, if ATM registration was successful, this feature writes a registration record to Cassandra including the subscriber’s MSISDN, the site’s GT (the sentinelIPSMGWAddress
in the shared IPSMGW configuration), and the current timestamp.
When a user de-registers, the feature first checks the networkInitiatedDeRegistration
session state field. If the de-registration is user-initiated, the feature completes and allows the de-registration to proceed. If the de-registration is network-initiated, the feature reads the registration records in Cassandra for the subscriber (using their MSISDN), finds the one with the most recent timestamp, and compares the site GT in that record to the current site’s GT. If the site GTs match, the feature completes and allows the de-registration to proceed. If the site GTs are different (indicating that the subscriber most recently registered at a different site), then the feature sets the skipATMRegistration
session state field to true
so that the ATM de-registration is skipped.
Shared Configuration Profile
The shared configuration profile is used to make the basic configuration of Sentinel IP-SM-GW. The profile table name is IPSMGWSharedConfigProfileTable
.
Parameters
The profile table is scoped according to a Sentinel Selection Key. Typically there exists one profile for the platform.
Parameter | Type | Description | Example |
---|---|---|---|
ChargingOptions |
String[] |
Determines which kinds of charging to apply to MT and MO deliveries |
Zero or more of the following options can be enabled: IEC_MT_PS |
DeliveryOrder |
Enum |
Sets the order in which to try MT delivery - whether PS first, CS first or only one or the other |
The following options are available: |
HlrAddress |
String |
Contains the HLR SCCP Address, used for routing if |
'type=C7,ri=pcssn,pc=5,ssn=6' |
UseMsisdnAsHlrAddress |
Boolean |
Controls whether to address the outbound HLR leg using a GT address formed from the subscriber MSISDN, instead of using the configured |
false |
TemplateSmscAddress |
String |
Contains a Template SMSC SCCP Address, where the digits are replaced by the received SMSC address |
'type=C7,ri=gt,digits=0,ssn=6,national=false,nature=INTERNATIONAL,numbering=ISDN,gti=4,tt=0' |
SentinelOriginatingAddress |
String |
Defines the Sentinel IP-SM-GW SCCP Address |
'type=C7,ri=pcssn,pc=5,ssn=147' |
SentinelIPSMGWAddress |
String |
Defines the Sentinel IP-SM-GW international Address |
'address=653333333, nature=INTERNATIONAL, numberingPlan=ISDN' |
InvokeTimeout |
Long |
Timeout in ms when invoking MAP operations |
5000 |
SentinelTerminatingDomain |
String |
Domain defined by the operator to compose SIP URIs from the MSISDN |
domain.com |
ICSCFURI |
String |
The I-CSCF SIP URI that will be used to route outbound SIP MESSAGE requests (see SIP Transports and Routing) |
sip:127.0.0.1:5052;lr;transport=tcp |
SipTransport |
String |
The SIP transport for the IPSMGW’s own SIP URI, used in the |
"udp" or "tcp" |
SmsContentSizeThreshold |
String |
If the length of the message content falls within the configured maximum then send the ForwardSM as part of the TC-BEGIN. As a special case a configured max size of 0 disables this functionality regardless of the actual content length. |
0 |
SriSmDeliveryNotIntended |
Boolean |
If true, specify the SmDeliveryNotIntended flag when performing an SRI for SM IMSI-only query (i.e. during SMMA callflows). The FetchIMSI feature will use a v2 MAP dialog if set to false, and a v3 MAP dialog when set to true. Please read the important note on the FetchIMSI feature page. |
False |
SubscribeToUEReachabilityForIP |
Boolean |
If true, request UEReachabilityForIP notifications from the HSS on certain PS Delivery failures. |
True |
UseGtAsCallingParty |
Boolean |
When accepting an OpenRequest, the SCCP responder address in the OpenAccept will, by default, be set to the value of the SCCP called party in the OpenRequest. If This is useful when the inbound sccp-called-party has been modified by a network element to use PCSSN routing, but GT routing is required for establishing the TCAP dialog. |
False |
SuppressHLRInteraction |
boolean |
If true, no MAP messages will be sent to the HLR. Can only be set to true when DeliveryOrder is PS_ONLY. For more information, refer to Suppression of HLR Interaction |
false |
Short Message Memory Available Features
These features relate to the Short Message Memory Available Submission path from the UE to the network. This occurs when the UE indicates that it has memory available to receive short messages, having previously indicated that it did not have available memory.
Feature | What it does |
---|---|
extracts the MSISDN from a SMMA message, then sends an RP-ACK to the SMMA request |
SMMA Response
This feature extracts the MSISDN from a SMMA message, then sends an RP-ACK to the SMMA request
Feature cheat sheet
Feature Name | Network Operator Data | Used in PlanId(s) | Stateful or Stateless | POJO Feature or SBB Feature |
---|---|---|---|---|
IPSMGWSMMAResonse |
No |
SMMA |
Stateless |
POJO |
Feature parameters
The Handle SMMA feature supports the following parameters that may be passed in a feature execution script run statement:
Name | Allowed Values | Description |
---|---|---|
mode |
|
This is used to determine what action the feature should take when run. |
Session Input variables
The feature reads the following fields in Session State
Session State variable name | Variable type | Comments |
---|---|---|
SRI4SMResult |
enum |
Indicates if the SendRoutingInfoForSM request has succeeded. Allowed values are |
SRI4SMError |
TcapError |
The TcapError received in response to the SendRoutingInfoForSMRequest |
ReadyForSMResult |
enum |
Indicates if the ReadyForSM request has succeeded. Allowed values are |
ReadyForSMError |
TcapError |
The TcapError received in response to the ReadyForSM |
Session Output variables
The feature sets the following fields in Session State
Session State variable name | Variable type | Comments |
---|---|---|
MSISDN |
String |
The MSISDN to be used by the Fetch IMSI feature |
Statistics
IPSMGWSMMAResponse statistics are tracked by the sentinel.ipsmgw SBB and can be found under the following parameter set in REM:
SLEE-Usage → sentinel.ipsmgw service → sentinel.ipsmgw SBB → feature → IPSMGWSMMAResponse
or with rhino-stats:
"SLEE-Usage.Services.ServiceID[name=sentinel.ipsmgw,vendor=OpenCloud,version=3.1.0].SbbID[name=sentinel.ipsmgw,vendor=OpenCloud,version=3.1.0].feature.IPSMGWSMMAResponse"
Name | Description |
---|---|
SavedMSISDN |
Incremented when the MSISDN has been extracted from the incoming SIP MESSAGE |
SentRPACK |
Incremented when the RP-ACK message is successfully sent to the I-CSCF |
FailedToSendRPACK |
Incremented when the RP-ACK message fails to be sent to the I-CSCF |
SentRPError |
Incremented when the RP-ERROR message is successfully sent to the I-CSCF |
FailedToSendRPError |
Incremented when the RP-ERROR message fails to be sent to the I-CSCF |
FailedToPrepareSIPMessage |
Incremented when we unable to prepare a SIP MESSAGE for the RP-ACK or RP-ERROR to be sent in |
NoPAIAvailable |
Incremented when the |
HLRSuppressed |
Incremented when HLR Interaction is suppressed |
Configuration
The feature is configured with configuration scoped according to a Sentinel Selection Key. The Profile Table used to hold feature configuration is IPSMGWSharedConfigProfileTable
.
The following attributes are available
Attributes | Type | Meaning |
---|---|---|
ICSCFURI |
String |
The I-CSCF SIP URI that will be used to route outbound SIP MESSAGE requests (see SIP Transports and Routing) |
SuppressHLRInteraction |
boolean |
If true, no MAP messages will be sent to the HLR. Can only be set to true when DeliveryOrder is PS_ONLY. For more information, refer to Suppression of HLR Interaction |
Behaviour
When run with mode prepare
and the trigger is a SIP MESSAGE that contains a SMMA, the feature will send a 202 response, then attempt to derive an MSISDN from the 'P-Asserted-Identity' header. The feature will also use the incoming SIP MESSAGE to prepare the responding SIP MESSAGE request that will contain either the RP-ACK or RP-ERROR. This response is prepared but not sent, unless the IPSMGW is configured to suppress HLR Interaction (see Suppression of HLR Interaction), in which case the MESSAGE is sent with RP_ACK
When run with mode send
and the trigger is a TCAP response the feature checks the SRI4SMResult
, SRI4SMError
, ReadyForSMResult
, and ReadyForSMError
session state fields and sends the RP response based on their values.
If both SRI4SMResult
and ReadyForSMResult
indicate success it will send an RP-ACK. If either one of them indicates failure it will map the TCAP error to an RP-ERROR cause based on the table below:
TCAP error | RP-ERROR cause |
---|---|
|
|
|
|
|
|
|
|
|
|
Any other value |
|
The prepared SIP Message request is then sent.
If the session state fields indicate that the SendRoutingInfoForSM and/or ReadyForSM operations have not been attempted then the feature will not do anything.
USSI Features
These features relate to processing USSI requests.
Feature | What it does |
---|---|
analyses an incoming INVITE request to determine if it is a USSI request. |
|
handles the SIP side of the USSI conversation. |
|
converts USSD text to/from encoded forms |
|
generates and sends a USSD request to an HLR, and handles the result |
Convert USSI Text
This feature converts USSD text to/from encoded forms
Feature cheat sheet
Feature Name | Network Operator Data | Used in PlanId(s) | Stateful or Stateless | POJO Feature or SBB Feature |
---|---|---|---|---|
ConvertUssiText |
No |
USSI |
Stateless |
POJO |
Feature parameters
The Convert USSI Text feature supports the following parameters that may be passed in a feature execution script run statement:
Name | Allowed Values | Description |
---|---|---|
mode |
|
This is used to determine what action the feature should take when run. |
Session Input variables
The feature reads the following fields in Session State
Session State variable name | Variable type | Comments |
---|---|---|
UssdTextAsText |
String |
USSD text to be encoded into a byte array |
UssdTextAsBytes |
byte[] |
Byte array to be decoded to USSD text |
Session Output variables
The feature sets the following fields in Session State
Session State variable name | Variable type | Comments |
---|---|---|
UssdTextAsText |
String |
USSD text that has been decoded from a byte array |
UssdTextAsBytes |
byte[] |
Byte array that has been encoded from USSD text |
Statistics
ConvertUssiText statistics are tracked by the sentinel.ipsmgw SBB and can be found under the following parameter set in REM:
SLEE-Usage → sentinel.ipsmgw service → sentinel.ipsmgw SBB → feature → ConvertUssiText
or with rhino-stats:
"SLEE-Usage.Services.ServiceID[name=sentinel.ipsmgw,vendor=OpenCloud,version=3.1.0].SbbID[name=sentinel.ipsmgw,vendor=OpenCloud,version=3.1.0].feature.ConvertUssiText"
Name | Description |
---|---|
Started |
Incremented when the feature is started. |
FailedToStart |
Incremented when Sentinel encounters an error while attempting to start the feature. |
IssuedWarning |
Incremented when a non-fatal problem is encountered and the feature and issues a warning. |
FailedDuringExecution |
Incremented when a fatal problem is encountered and the feature cannot execute correctly. |
TimedOut |
Incremented when the feature takes too long to complete and Sentinel aborts execution. |
StartedXmlToEncoded |
Incremented when the feature is started in the XmlToEncoded mode |
StartedEncodedToXml |
Incremented when the feature is started in the EncodedToXml mode |
RejectWithDefaultMessage |
Incremented when the feature is started in the XmlToEncode mode and the configuration states that the feature should reject with a default message |
Behaviour
This feature reads one of the two session state fields and encodes or decodes it into the other session state field. The encoding is done as GSM 7-bit.
The feature will encode or decode based on the feature parameter passed to it from the feature script.
-
When started with
xmlToEncoded
the feature reads fromUssdTextAsText
and encodes it intoUssdTextAsBytes
ifRejectAllUssiWithDefaultErrorMessage
is not set. In the event thatRejectAllUssiWithDefaultErrorMessage
is set the feature will instead stop Ussi conversation and a static message will be generated by another feature downstream. Also the features for ussi will not contact the HLR. -
When started with
encodedToXml
the feature reads fromUssdTextAsBytes
and decodes it intoUssdTextAsText
.
Determine Ussi Mode
This feature analyses an incoming INVITE request to determine if it is a USSI request.
Feature cheat sheet
Feature Name | Network Operator Data | Used in PlanId(s) | Stateful or Stateless | POJO Feature or SBB Feature |
---|---|---|---|---|
DetermineUssiMode |
No |
All INVITE Sessions |
Stateless |
POJO |
Statistics
DetermineUssiMode statistics are tracked by the sentinel.ipsmgw SBB and can be found under the following parameter set in REM:
SLEE-Usage → sentinel.ipsmgw service → sentinel.ipsmgw SBB → feature → DetermineUssiMode
or with rhino-stats:
"SLEE-Usage.Services.ServiceID[name=sentinel.ipsmgw,vendor=OpenCloud,version=3.1.0].SbbID[name=sentinel.ipsmgw,vendor=OpenCloud,version=3.1.0].feature.DetermineUssiMode"
Name | Description |
---|---|
Started |
Incremented when the feature is started. |
FailedToStart |
Incremented when Sentinel encounters an error while attempting to start the feature. |
IssuedWarning |
Incremented when a non-fatal problem is encountered and the feature and issues a warning. |
FailedDuringExecution |
Incremented when a fatal problem is encountered and the feature cannot execute correctly. |
TimedOut |
Incremented when the feature takes too long to complete and Sentinel aborts execution. |
MessageNotUssiRequest |
Incremented when it is determined that the incoming request is not a USSI request. |
MessageIsUssiRequest |
Incremented when it is determined that the incoming request is a USSI request. |
Behaviour
On receiving an incoming SIP request, this feature checks the request against the following conditions:
-
The request method is
INVITE
. -
The Request-URI is a SIP URI (i.e. the URI starts with
sip:
). -
The Request-URI has a
user
parameter with the value set todialstring
. -
The user part of the Request-URI is a valid USSD dial string according to 3GPP TS 22.090.
If all of the conditions are met, the feature will increment the MessageIsUssiRequest
statistic and finish execution, allowing message processing to proceed.
If any of the conditions are not met, the feature will increment the MessageNotUssiRequest
statistic, and instruct the SIP session to proxy the request without recording Sentinel on the route. The feature will then finish execution.
Handle Mobile Initiated USSD
This feature generates and sends a USSD request to an HLR, and handles the result .
Feature cheat sheet
Feature Name | Network Operator Data | Used in PlanId(s) | Stateful or Stateless | POJO Feature or SBB Feature |
---|---|---|---|---|
HandleMobileInitiatedUssd |
No |
USSI |
Stateless |
POJO |
Session Input variables
The feature reads the following fields in Session State
Session State variable name | Variable type | Comments |
---|---|---|
MSISDN |
String |
The MSISDN to use in the MAPProcessUnstructuredSS_Request operation |
UssdLanguageDcsMapping |
UssdLanguageDcsMapping |
The Data Coding Scheme to use in the MAPProcessUnstructuredSS_Request operation |
UssdTextAsBytes |
byte [] |
The text to use in the MAPProcessUnstructuredSS_Request operation, in an encoding matching the data coding scheme. |
Session Output variables
The feature sets the following fields in Session State
Session State variable name | Variable type | Comments |
---|---|---|
UssdLanguageDcsMapping |
UssdLanguageDcsMapping |
The Data Coding Scheme retrieved from the MAPProcessUnstructuredSS_Request ack (if successful). |
UssdTextAsBytes |
byte [] |
The text retrieved from the MAPProcessUnstructuredSS_Request ack (if successful), in an encoding matching the data coding scheme. |
UssiErrorCode |
int |
The Ussi Error codes as defined in TS 24390-c60 (if unsuccessful). |
UssdConversationComplete |
boolean |
Whether the conversation is complete and a BYE should be sent to the initiating party. |
Statistics
HandleMobileInitiatedUssd statistics are tracked by the sentinel.ipsmgw SBB and can be found under the following parameter set in REM:
SLEE-Usage → sentinel.ipsmgw service → sentinel.ipsmgw SBB → feature → HandleMobileInitiatedUssd
or with rhino-stats:
"SLEE-Usage.Services.ServiceID[name=sentinel.ipsmgw,vendor=OpenCloud,version=3.1.0].SbbID[name=sentinel.ipsmgw,vendor=OpenCloud,version=3.1.0].feature.HandleMobileInitiatedUssd"
Name | Description |
---|---|
SendProcessUnstructuredSSRequestSucceeded |
Incremented when a MAPProcessUnstructuredSS_Request is sent to the HLR |
SendProcessUnstructuredSSRequestFailed |
Incremented when an attempt to send a MAPProcessUnstructuredSS_Request fails |
ReceiveProcessUnstructuredSSRequestAck |
Incremented when the feature receives a MAPProcessUnstructuredSS_Request ack |
ReceiveProcessUnstructuredSSRequestError |
Incremented when the feature receives a MAP error in response to the request |
ReceiveUnexpectedError |
Incremented when the feature receives an error that is not specifically mapped to an error code |
ReceiveUnstructuredSSNotify |
Incremented when the feature receives a MAPUnstructuredSSNotify_Request from the HLR |
Configuration
The feature is configured with configuration scoped according to a Sentinel Selection Key. The Profile Table used to hold feature configuration is IPSMGWSharedConfigProfileTable
.
The following attributes are available
Attributes | Type | Meaning |
---|---|---|
HlrAddress |
String |
Address of the HLR to request the IMSI from, used when establishing the MAP dialog if |
UseMsisdnAsHlrAddress |
Boolean |
Controls whether to address the outbound HLR leg using a GT address formed from the subscriber MSISDN, instead of using the configured |
SentinelOriginatingAddress |
String |
Address of Sentinel used when establishing the MAP dialog |
Using MSISDN as HLR Address
The Fetch IMSI feature can optionally address the HLR leg using a GT address formed from the inbound subscriber MSISDN, as opposed to using the destination addresses configured in the IPSMGWMapProxyConfigProfileTable
profile table described above.
This behaviour can be enabled or disabled by setting the UseMsisdnAsHlrAddress
attribute in the Shared Configuration Profile
.
MAP Application Context
The feature uses MAP Application Context networkUnstructuredSsContext
. This application context was added in GSM MAP Phase 2.
Behaviour
When the feature is triggered on a SIP invite, the feature will construct a MAPProcessUnstructuredSS_Request message from values in session state. The Handle USSI Invite and Convert USSI Text features are responsible for correctly setting the session state fields.
When the HLR responds to the message, or the TCAP connection times out, the feature will indicate (through session state) that a response to the A-Party should be generated. If the HLR sent a success response, the feature will retrieve the USSD text and data coding scheme from the result, and store those values in session state. If the HLR sent an error response appropriate to the operation, the feature will store the corresponding value in session state (and leave the text and DCS fields blank). If an unrecognized error occurs - eg a TCAP timeout, an abort, or an unrecognized MAP error - the USSI Error Code session state field will be set to 1 (and the text and DCS fields will be left blank. If the HLR attempts to send a MAPUnstructuredSSNotify_Request, to begin a multipart USSD operation, the feature will respond with a TCAP User Abort, and set the Error Code session state to 1.
Handle USSI Invite
This feature handles the SIP side of the USSI conversation.
Feature cheat sheet
Feature Name | Network Operator Data | Used in PlanId(s) | Stateful or Stateless | POJO Feature or SBB Feature |
---|---|---|---|---|
HandleUssiInvite |
No |
USSI |
Stateless with FSM encoded into session state |
POJO |
Session Input variables
The feature reads the following fields in Session State
Session State variable name | Variable type | Comments |
---|---|---|
UssdTextAsText |
String |
The data to put in the <ussd-string> element of the <ussd-data> xml in the message body |
UssdLanguageDcsMapping |
enum |
An enum that indicates the supported language to put in the <language> element of the <ussd-data> xml |
UssdConversationComplete |
boolean |
Set by the Handle Mobile Initiated Ussd feature to indicate the USSD conversation is finished. |
UssiErrorCode |
int |
Set by the Handle Mobile Initiated Ussd if the response from the HLR is an error |
Session Output variables
The feature sets the following fields in Session State
Session State variable name | Variable type | Comments |
---|---|---|
MSISDN |
String |
The MSISDN extracted from the 'P-Asserted-Identity' header. |
UssdTextAsText |
String |
The <ussd-string> element of the <ussd-data> xml from the message body of the INVITE |
UssdLanguageDcsMapping |
enum |
And enum that represents the <language> element of the <ussd-data> xml from the message body of the INVITE |
Statistics
HandleUssiInvite statistics are tracked by the sentinel.ipsmgw SBB and can be found under the following parameter set in REM:
SLEE-Usage → sentinel.ipsmgw service → sentinel.ipsmgw SBB → feature → HandleUssiInvite
or with rhino-stats:
"SLEE-Usage.Services.ServiceID[name=sentinel.ipsmgw,vendor=OpenCloud,version=3.1.0].SbbID[name=sentinel.ipsmgw,vendor=OpenCloud,version=3.1.0].feature.HandleUssiInvite"
Name | Description |
---|---|
Started |
Incremented when the feature is started. |
FailedToStart |
Incremented when Sentinel encounters an error while attempting to start the feature. |
IssuedWarning |
Incremented when a non-fatal problem is encountered and the feature and issues a warning. |
FailedDuringExecution |
Incremented when a fatal problem is encountered and the feature cannot execute correctly. |
TimedOut |
Incremented when the feature takes too long to complete and Sentinel aborts execution. |
ReceivedUssiInvite |
Incremented when the feature receives an INVITE that has a multipart/mixed message body with both USSD XML and SDP. |
SavedUssiData |
Incremented when the USSD XML data is successfully saved in session state. |
SentInvite200Response |
Incremented when the feature sends a 200 OK response to the INVITE. |
ReceivedInviteAck |
Incremented when the feature receives the ACK for the 200 OK. |
SentByeWithSuccess |
Incremented when the feature sends a BYE with successfully retrieved USSD data. |
SentByeWithError |
Incremented when the feature sends a BYE with a error in the USSD text. |
ReceivedBye200Response |
Incremented when the feature receives the 200 OK to the BYE. |
EndSessionInError |
Incremented when the feature ends the session due to an error. |
Behaviour
This features handles all of the SIP messaging for a USSI conversation.
It starts by receiving the INVITE and checking it for an SDP body with media ports set to 0, as well as the presence of the ussd-data XML body. When this is confirmed it will save the 'ussd-string' and 'language' fields into session state as well as extracting the MSISDN from the 'P-Asserted-Identity' header.
It will then send a '200 OK' response with the following set:
-
Recv-Info header field containing the g.3gpp.ussd info-package name
-
The 'Accept' header field containing the 'application/vnd.3gpp.ussd+xml', 'application/sdp' and 'multipart/mixed' MIME types
-
SDP answer as described in subclause 4.5.2 of 3GPP TS 24.390
The feature then waits for the 'ACK' to the '200 OK', as well as for the MAP conversation to complete which is handled by the Handle Mobile Initiated Ussd feature. When both of these requirements are satisfied the feature will send a 'BYE' with a application/vnd.3gpp.ussd+xml MIME body, as described in subclause 5.1.3 of 3GPP TS 24.390 including a <ussd-string> element and a <language> element. Or a 'BYE' with a application/vnd.3gpp.ussd+xml MIME body, as described in subclause 5.1.3 of 3GPP TS 24.390 including a <error-code> element.
Mappers
Customising Mappers
Sentinel IPSMGW includes a module pack that can be used to extend all of these mappers:
ipsmgw-mappers
See Customising Mappers in the IPSMGW SDK guide for instructions.
IPSMGWChargingInstanceToCCR
Description |
Generates an Ro Credit-Control-Request for online charging, using the |
---|---|
From |
|
To |
|
See Charging Content AVPs for more information on which AVPs are included in Sentinel IPSMGW CCRs.
MTFSMToSessionCounterAddress
Description |
Generates a SessionCounterAddress for MT charging. |
---|---|
From |
|
To |
|
Key | Value or source |
---|---|
Subscriber-Id |
|
Service-Id |
|
Cc-Unit-Type |
|
Suppression of HLR Interaction
This page presents detailed information related to HLR Interaction Suppression mode for the Sentinel IP Short Message Gateway product.
Overview
By means of a configuration flag, 'suppressHLRInteraction' in Shared Configuration Profile, the IP-SM-GW may suppress all MAP messaging sent to the HLR. This mode is only available when DeliveryOrder is PS_ONLY.
-
ReportSM in PS Only Delivery flows
-
SendRoutingInfoForSM in Registration, SMMA and UE Reachability for IP Notification flows
-
ReadyForSM in Registration, SMMA and UE Reachability for IP Notification flows
-
AnyTimeModification in Registration flows
-
IPSMGWPSDelivery: ReportSM with DeliveryStatus is omitted.
-
IPSMGWATMRegistration: the feature is inhibited
-
IPSMGWFetchIMSI: the feature is inhibited
-
IPSMGWReadyForSM: the feature is inhibited
-
SMMAResponseFeature: the feature prepares and sends the answer MESSAGE with RP_ACK when called in 'prepare' mode
In all cases a specific counter is increased to report the suppression.
Message flows
PS Only Delivery
In the routing part of the flow, it is assumed the SMSC will send requests directly to IPSMGW
In the FSM part, ReportSM with Delivery Status will not be sent.
Registration
On registration, no AnytimeModification, SendRoutingInfoForSM or ReadyForSM messages are be sent to the HLR
On deregistration, ATM is suppressed
TCAP Application Context Negotiation Flows
This page presents detailed information related to TCAP Application Context Negotiation for the Sentinel IP Short Message Gateway product.
SRI for SM receipt handling
The Routing Info for Short Message (SRI-SM) Application Context and request are proxied "as-is" between the received SRI-SM and that sent to the HLR. Therefore any errors from the HLR are proxied back towards the initiator.
For more information on the logic of the flow, please refer to Flows for SMS delivery
MT Forward Short Message negotiation
The IP-SM-GW may sit "in-between" any particular SMSC and the home network’s MSCs and SGSNs. As the IP-SM-GW forces MT Forward Short Message operations to route through it, it must implement TCAP Application Context Negotiation.
Each case is represented by a flow.
Mapping between versions for Forward Short Message Errors
MAP Phases 1 and 2 do not define a result type for the Forward Short Message operation. They do define errors. Therefore if a TC-END is received, where there are no errors, the operation is a success.
The different MAP Phases define similar yet different errors for the operations. When application contexts have been downgraded through negotiation, the errors need to be upgraded.
Phase 1 to Phase 2 Error Mapping
An error when using MAP Phase 1 towards the MSC/SGSN needs to be translated to the appropriate error when replying to Phase 2 towards the SMSC. An example is below.
Phase 1 error response | Mapped Phase 2 error response |
---|---|
absentSubscriber |
absentSubscriber |
facilityNotSupported |
facilityNotSupported |
illegalMS |
illegalSubscriber |
sm_DeliveryFailure |
sm_DeliveryFailure |
systemFailure |
systemFailure |
unexpectedDataValue |
unexpectedDataValue |
unidentifiedSubscriber |
unidentifiedSubscriber |
Phase 1 to Phase 3 Error Mapping
An error when using MAP Phase 1 towards the MSC/SGSN needs to be translated to the appropriate error when replying to Phase 3 towards the SMSC. An example is as follows:
Phase 1 error response | Mapped Phase 3 error response |
---|---|
absentSubscriber |
absentSubscriberSM |
facilityNotSupported |
facilityNotSupported |
illegalMS |
illegalSubscriber |
sm_DeliveryFailure |
sm_DeliveryFailure |
systemFailure |
systemFailure |
unexpectedDataValue |
unexpectedDataValue |
unidentifiedSubscriber |
unidentifiedSubscriber |
Phase 2 to Phase 3 Error Mapping
An error when using MAP Phase 2 towards the MSC/SGSN needs to be translated to the appropriate error when replying to Phase 3 towards the SMSC.
Phase 2 error response | Mapped Phase 3 error response |
---|---|
absentSubscriber |
absentSubscriberSM |
dataMissing |
dataMissing |
facilityNotSupported |
facilityNotSupported |
illegalEquipment |
illegalEquipment |
illegalSubscriber |
illegalSubscriber |
sm_DeliveryFailure |
sm_DeliveryFailure |
subscriberBusyForMT_SMS |
subscriberBusyForMT_SMS |
systemFailure |
systemFailure |
unexpectedDataValue |
unexpectedDataValue |
unidentifiedSubscriber |
unidentifiedSubscriber |
Charging Information
Charging Information describes the format and content of CDR files, and the information present in Diameter Ro.
Topics
-
CDR Formats — describes the formats used for CDRs
-
Charging Content AVPs — describes the populated AVPs for both online and offline charging
-
Ro Interface AVPs — describes the population of AVPs on the Ro interface
-
Sizing AVP CDRs — describes storage requirements for AVP CDRs
-
Working with CDRs — describes tooling to extract the content of CDRs
CDR Formats
AVP CDRs
An AVP CDR is an OpenCloud defined CDR that contains AVPs. This type of CDR is consistent with the approaches used in Diameter Ro and Diameter Rf interfaces. An AVP CDR contains AVPs that are standardised (e.g. 3GPP and IETF), or non-standardised (e.g. product specific or project specific).
AVP CDRs can almost be considered an "on-disk" form of the content contained in the Rf interface.
Topics
-
AVP CDR Format — describes the formats used for AVP CDRs
AVP CDR Format
AVP CDRs have logical content, and an on-disk format.
Logical content
Each CDR inside a CDR file has logical content. We use a BNF syntax to describe this logical content.
CDR ::= [ Subscription-Id ] [ IMS-Information ] [ User-Equipment-Info ] *[ Multiple-Services-Credit-Control ] [ OC-Call-Type ] [ OC-Service-Type ] [ OC-Charging-Result ] *[ OC-OCS-Session-Id ] [ OC-OCS-Session-Termination-Cause ] [ OC-Sentinel-Error ] *[ OC-Charging-Instance ] [ OC-Event-Id ] [ OC-Call-Id ] [ OC-End-Session-Cause ] [ OC-Session-Start-Time ] [ OC-Session-Established-Time ] [ OC-Session-End-Time ] [ OC-Selection-Key ] [ OC-Plan-Id ] [ OC-Submit-Report-Type ] [ OC-Correlated-Id ] [ OC-MT-PS-Delivery-Result ] [ OC-MT-CS-Delivery-Result ] [ OC-IMPU ] [ SMS-Information ] *[ AVP ]
Logically this means that an individual CDR has optional content. It may have zero or one Subscription-Id AVP, zero or one IMS-Information AVP, and so-on. It may have zero or more OC-OCS-Session-Id AVPs, and so-on.
A CDR inside the CDR file is not an AVP. It is a protobuf record, and as such may contain additional "root" AVPs. So, for example an application may use the format, but add a LCS-Information AVP, or custom AVP.
You could consider each CDR to be roughly equivalent to the Service-Information AVP, yet more flexible/extensible regarding its content. This is because the Service-Information AVP is essentially closed for extension by non-3GPP groups.
To view the population of AVPs in use, refer to Charging Content AVPs
On disk format
AVP CDRs are written using Google protocol buffers (protobuf).
An AVP CDR file has a protobuf schema. This schema allows any AVP to be written to a CDR.
package com.opencloud.cdrformat; // AVP based CDR message AvpCdr { repeated AVP avps = 1; message AVP { required bytes avpData = 1; // The Diameter binary encoded AVP data required string interfaceName = 2; // The interface which the AVP is being written out as, e.g "Rf", "Ro" required string specRevision = 3; // E.g. "vcb0" optional string avpName = 4; } }
Legacy CDR Format
The Legacy CDR format has an on-disk format defined using Google protocol buffers (aka protobuf
).
There is a common "types definition" schema file that is used by multiple Sentinel Services for their CDRs. These types are called "base types". Each Sentinel Service then defines its own CDRs using these types and defining its own types.
Base types
The base types are used in CDRs for Sentinel SS7, Sentinel Diameter Mediation.
Unresolved directive in ipsmgw-administration-guide/charging-information/cdr-formats/legacy-cdr-format.adoc - include::/mnt/ephemeral0/workspace/product/sentinel/sentinel-ipsmgw/release-3.1.0/Auto/ipsmgw-docs/ipsmgw-docs/target/generated/ipsmgw-administration-guide/sentinel-cdr-common-base-cdr-types.proto[]
Sentinel SS7 Service CDR format
The Sentinel SS7 service defines two CDR formats, one for CAP calls, and the other for CAP3 SMS.
CAP Calls
CAP call use the following format for its CDR files (out of the box).
Unresolved directive in ipsmgw-administration-guide/charging-information/cdr-formats/legacy-cdr-format.adoc - include::/mnt/ephemeral0/workspace/product/sentinel/sentinel-ipsmgw/release-3.1.0/Auto/ipsmgw-docs/ipsmgw-docs/target/generated/ipsmgw-administration-guide/sentinel-ss7-cdr-format.proto[]
CAP3 SMS
CAP3 SMS support ses the following format for its CDR files (out of the box).
Unresolved directive in ipsmgw-administration-guide/charging-information/cdr-formats/legacy-cdr-format.adoc - include::/mnt/ephemeral0/workspace/product/sentinel/sentinel-ipsmgw/release-3.1.0/Auto/ipsmgw-docs/ipsmgw-docs/target/generated/ipsmgw-administration-guide/sentinel-ss7-cdr-format-sms.proto[]
Sentinel Diameter Mediation Service CDR format
The Sentinel Diameter Mediation service defines a CDR format.
Unresolved directive in ipsmgw-administration-guide/charging-information/cdr-formats/legacy-cdr-format.adoc - include::/mnt/ephemeral0/workspace/product/sentinel/sentinel-ipsmgw/release-3.1.0/Auto/ipsmgw-docs/ipsmgw-docs/target/generated/ipsmgw-administration-guide/sentinel-diameter-cdr-format.proto[]
Charging Content AVPs
The population of AVPs for Sentinel IPSMGW is described on this page. A definition of the AVPs used for the Sentinel IPSMGW product is provided on Sentinel IPSMGW AVP definitions.
Detecting Online Charging
The OC-Charging-Result AVP in a CDR or ACR indicates whether online (Diameter Ro) charging was used for a session. This may be used to determine if further action is needed when processing CDRs offline.
-
An
OC-Charging-Result
value of-1
means that online charging was not used for the session. -
Otherwise the value is set to the Diameter
Result-Code
AVP value.
Populated AVPs in the Multiple-Services-Credit-Control AVP
The Multiple-Services-Credit-Control AVP is of type grouped, and is defined in RFC 4006. Section 7.1.4 of 3GPP TS 32.299 defines it with additional 3GPP specific parameters and states some IETF parameters are not used in the 3GPP.
AVP Name | Specification reference | Included in CDR | Included in CCR | Included in ACR | Comments |
---|---|---|---|---|---|
Requested-Service-Unit |
IETF RFC 4006 |
No |
Yes |
No |
Used in the CCR. The CDR represents this information in the OC-Session-Counter AVP |
Used-Service-Unit |
IETF RFC 4006 and 3GPP TS 32.299 |
No |
Yes |
No |
Used in the CCR according to Populated AVPs in the Used-Service-Unit AVP. The CDR represents this information in the OC-Session-Counter AVP |
Service-Identifier |
IETF RFC 4006 |
Yes |
Yes |
Yes |
For Originating attempts the AVP has the value |
Rating-Group |
IETF RFC 4006 and 3GPP TS 32.299 v12.11.0 section 7.1.10 |
No |
Yes |
No |
This AVP is set according to Session Counters and the |
Reporting-Reason |
3GPP TS 32.299 v12.11.0 section 7.2.175 |
No |
Yes |
No |
|
Trigger |
3GPP TS 32.299 v12.11.0 section 7.2.235 |
No |
No |
No |
|
PS-Furnish-Charging-Information |
3GPP TS 32.299 v12.11.0 section 7.2.157 |
No |
No |
No |
|
Refund-Information |
3GPP TS 32.299 v12.11.0 section 7.2.171 |
No |
No |
No |
|
AF-Correlation-Information |
3GPP TS 32.299 v12.11.0 section 7.2.11 |
No |
No |
No |
|
Envelope |
3GPP TS 32.299 v12.11.0 section 7.2.59 |
No |
No |
No |
|
Envelope-Reporting |
3GPP TS 32.299 v12.11.0 section 7.2.61 |
No |
No |
No |
|
Time-Quota-Mechanism |
3GPP TS 32.299 v12.11.0 section 7.2.228 |
No |
No |
No |
|
Service-Specific-Info |
3GPP TS 32.299 v12.11.0 section 7.2.195 |
No |
No |
No |
|
QoS-Information |
3GPP TS 29.212 |
No |
No |
No |
The BNF grammar for this AVP in 32.299 v12.11.0 is as follows:
<Multiple-Services-Credit-Control> ::= < AVP Header: 456 > [ Granted-Service-Unit ] // not used in CCR [ Requested-Service-Unit ] * [ Used-Service-Unit ] [ Tariff-Change-Usage ] // not used in 3GPP * [ Service-Identifier ] [ Rating-Group ] * [ G-S-U-Pool-Reference ] // not used in CCR [ Validity-Time ] // not used in CCR [ Result-Code ] // not used in CCR [ Final-Unit-Indication ] // not used in CCR [ Time-Quota-Threshold ] // not used in CCR [ Volume-Quota-Threshold ] // not used in CCR [ Unit-Quota-Threshold ] // not used in CCR [ Quota-Holding-Time ] // not used in CCR [ Quota-Consumption-Time ] // not used in CCR * [ Reporting-Reason ] [ Trigger ] [ PS-Furnish-Charging-Information ] [ Refund-Information ] * [ AF-Correlation-Information] * [ Envelope ] [ Envelope-Reporting ] [ Time-Quota-Mechanism ] * [ Service-Specific-Info ] [ QoS-Information ] * [ AVP ] // not used in 3GPP
Populated AVPs in the Used-Service-Unit AVP
The Used-Service-Unit AVP is defined in IETF RFC 4006, and then its BNF is modified slightly in 3GPP TS 32.299 section 7.1.9.
AVP Name | Specification reference | Included in CDR | Included in CCR | Included in ACR | Comments |
---|---|---|---|---|---|
Reporting-Reason |
3GPP TS 32.299 v12.11.0 section 7.2.175 |
No |
No |
No |
|
Tariff-Change-Usage |
IETF RFC 4006 |
No |
No |
No |
|
CC-Time |
IETF RFC 4006 |
No |
Yes |
No |
Used by default as the unit type for SIP Sessions |
CC-Money |
IETF RFC 4006 |
No |
No typically |
No |
Not used out-of-the-box for Sentinel SIP |
CC-Total-Octets |
IETF RFC 4006 |
No |
Not typically |
No |
Not used out-of-the-box for Sentinel SIP |
CC-Input-Octets |
IETF RFC 4006 |
No |
Not typically |
No |
Not used out-of-the-box for Sentinel SIP |
CC-Output-Octets |
IETF RFC 4006 |
No |
Not typically |
No |
Not used out-of-the-box for Sentinel SIP |
The 3GPP definition (in v12.11.0) is
<Used-Service-Unit> ::= < AVP Header: 446 > [ Reporting-Reason ] [ Tariff-Change-Usage ] [ CC-Time ] [ CC-Money ] // not used in 3GPP [ CC-Total-Octets ] [ CC-Input-Octets ] [ CC-Output-Octets ] [ CC-Service-Specific-Units ] *[ Event-Charging-TimeStamp ] *[ AVP ] // not used in 3GPP
Populated AVPs in the Service-Information AVP
The Service-Information AVP is defined in 3GPP TS 32.299 v12.11.0. It is a grouped AVP. This table lists the AVPs grouped within Service-Information and how the product populates them.
AVP Name | Specification reference | Included in CDR | Included in CCR | Included in ACR | Comments |
---|---|---|---|---|---|
SMS-Information |
32.299 v12.11.0 section 7.2.211 |
Yes |
Yes |
Yes |
|
MMTel-Information |
32.299 v12.11.0 section 7.2.111 |
Yes |
Yes |
Yes |
The Sentinel VoLTE product populates this AVP |
Subscription-Id |
IETF RFC 4006 |
Yes |
No |
Yes |
3GPP TS 32.299 v12.11.0 states that it should be set on the Rf interface, not the Ro interface (see section 7.2.149) |
AoC-Information |
32.299 v12.11.0 section 7.2.15 |
No |
No |
No |
Sentinel does not implement the advice of charge service out-of-the-box |
PS-Information |
32.299 v12.11.0 section 7.2.158 |
No |
No |
Yes |
PS-Information AVP contains EPC layer information. It is only added in ACRs as a means of sending the IMEI in the User-Equipment-Information AVP. |
IMS-Information |
32.299 v12.11.0 section 7.2.77 |
Yes |
Yes |
Yes |
See the IMS-Information table for further details |
MMS-Information |
32.299 v12.11.0 section 7.2.110 |
No |
No |
No |
Sentinel does not implement any MMS node roles out-of-the-box |
LCS-Information |
32.299 v12.11.0 section 7.2.89 |
No |
No |
No |
|
PoC-Information |
32.299 v12.11.0 section 7.2.144 |
No |
No |
No |
Sentinel does not implement the PoC service out-of-the-box |
MBMS-Information |
32.299 v12.11.0 section 7.2.99 |
No |
No |
No |
Sentinel does not implement the MBMS service out-of-the-box |
SMS-Information |
32.299 v12.11.0 section 7.2.211 |
No |
No |
No |
Sentinel does not implement the SMS service out-of-the-box |
VCS-Information |
32.299 v12.11.0 section 7.2.242A |
No |
No |
No |
|
MMTel-Information |
32.299 v12.11.0 section 7.2.111 |
Yes |
Yes |
Yes |
|
ProSe-Information |
32.299 v12.11.0 section 7.2.154I |
No |
No |
No |
|
Service-Generic-Information |
32.299 v12.11.0 section 7.2.191 |
No |
No |
No |
|
IM-Information |
32.299 v12.11.0 section 7.2.69 |
No |
No |
No |
Sentinel does not implement IM services out-of-the-box |
DCD-Information |
32.299 v12.11.0 section 7.2.50 |
No |
No |
No |
The BNF for the AVP is defined in section 7.2.149. It is as follows:
Service-Information :: = < AVP Header: 873> * [ Subscription-Id ] [ AoC-Information ] [ PS-Information ] [ IMS-Information ] [ MMS-Information ] [ LCS-Information ] [ PoC-Information ] [ MBMS-Information ] [ SMS-Information ] [ VCS-Information ] [ MMTel-Information ] [ ProSe-Information ] [ Service-Generic-Information ] [ IM-Information ] [ DCD-Information ]
Populated AVPs in the SMS-Information AVP
The SMS-Information AVP is a grouped AVP. It is defined in 32.299 v12.11.0 section 7.2.211.
AVP Name | Specification reference | Included in CDR | Included in CCR | Comments |
---|---|---|---|---|
SMS-Node |
32.299 v12.11.0 section 7.2.212 |
No |
Yes |
|
Client-Address |
32.299 v12.11.0 section 7.2.41 |
No |
Yes |
Configured IPSMGW GT address |
Data-Coding-Scheme |
32.299 v12.11.0 section 7.2.49 |
No |
Yes |
The |
SM-User-Data-Header |
32.299 v12.11.0 section 7.2.210 |
No |
Yes |
The |
SM-Status |
32.299 v12.11.0 section 7.2.209 |
No |
Yes |
The single octet |
SM-Discharge-Time |
32.299 v12.11.0 section 7.2.206 |
No |
Yes |
The |
Originator-Interface |
32.299 v12.11.0 section 7.2.126 |
No |
Yes |
|
Originator-Received-Address |
32.299 v12.11.0 section 7.2.127 |
Yes |
Yes |
Refer to Populated AVPs in the Originator-Received-Address AVP |
Recipient-Info |
32.299 v12.11.0 section 7.2.168 |
Yes |
Yes |
It has the following ABNF grammar:
SMS-Information :: = < AVP Header: 2000> [ SMS-Node ] [ Client-Address ] [ Originator-SCCP-Address ] [ SMSC-Address] [ Data-Coding-Scheme ] [ SM-Discharge-Time ] [ SM-Message-Type ] [ Originator-Interface ] [ SM-Protocol-ID ] [ Reply-Path-Requested ] [ SM-Status ] [ SM-User-Data-Header ] [ Number-Of-Messages-Sent ] * [ Recipient-Info ] [ Originator-Received-Address ] [ SM-Service-Type ]
Populated AVPs in the Originator-Interface AVP
The Originator-Interface AVP is a grouped AVP. It is defined in 3GPP TS 32.299 v12.11.0 section 7.2.126.
AVP Name | Specification reference | Included in CDR | Included in CCR | Comments |
---|---|---|---|---|
Interface-Id |
32.299 v12.11.0 section 7.2.71 |
Yes |
Yes |
|
Interface-Port |
32.299 v12.11.0 section 7.2.72 |
No |
Yes |
|
Interface-Text |
32.299 v12.11.0 section 7.2.73 |
No |
Yes |
|
Interface-Type |
32.299 v12.11.0 section 7.2.74 |
No |
Yes |
|
It has the following ABNF grammar:
Originator-Interface: = < AVP Header: 2009> [ Interface-Id ] [ Interface-Text ] [ Interface-Port ] [ Interface-Type ]
Populated AVPs in the Originator-Received-Address AVP
The Originator-Received-Address AVP is a grouped AVP. It is defined in 3GPP TS 32.299 v12.11.0 section 7.2.127.
AVP Name | Specification reference | Included in CDR | Included in CCR | Comments |
---|---|---|---|---|
Address-Type |
32.299 v12.11.0 section 7.2.9 |
Yes |
Yes |
|
Address-Data |
32.299 v12.11.0 section 7.2.7 |
Yes |
Yes |
For MT case: The |
Address-Domain |
32.299 v12.11.0 section 7.2.8 |
No |
No |
Not used |
It has the following ABNF grammar:
Originator-Received-Address ::= < AVP Header: 2027> [ Address-Type ] [ Address-Data ] [ Address-Domain ]
Populated AVPs in the Recipient-Info AVP
The Recipient-Info AVP is a grouped AVP. It is defined in 3GPP TS 32.299 v12.11.0 section 7.2.168.
AVP Name | Specification reference | Included in CDR | Included in CCR | Comments |
---|---|---|---|---|
Recipient-Address |
32.299 v12.11.0 section 7.2.167 |
Yes |
Yes |
It has the following ABNF grammar:
Recipient-Info :: = < AVP Header: 2026 > [ Destination-Interface ] * [ Recipient-Address ] * [ Recipient-Received-Address ] [ Recipient-SCCP-Address ] [ SM-Protocol-ID ]
Populated AVPs in the Recipient-Address AVP
The Recipient-Address AVP is a grouped AVP. It is defined in 3GPP TS 32.299 v12.11.0 section 7.2.167.
AVP Name | Specification reference | Included in CDR | Included in CCR | Comments |
---|---|---|---|---|
Address-Type |
32.299 v12.11.0 section 7.2.9 |
Yes |
Yes |
In the MO Submission case this is always |
Address-Data |
32.299 v12.11.0 section 7.2.7 |
Yes |
Yes |
In the MO Submission case this is taken from the |
It has the following ABNF grammar:
Recipient-Address :: = < AVP Header: 1201 > [ Address-Type ] [ Address-Data ] [ Address-Domain ] [ Addressee-Type ]
Populated AVPs in the IMS-Information AVP
The IMS-Information AVP is defined in 3GPP TS 32.299 v12.11.0. It is a grouped AVP. This table lists the AVPs grouped within IMS-Information and how the product populates them.
AVP Name | Specification reference | Included in CDR | Included in CCR | Included in ACR | Comments |
---|---|---|---|---|---|
Event-Type |
32.299 v12.11.0 section 7.2.65 |
Yes |
Yes |
Yes |
|
Role-Of-Node |
32.299 v12.11.0 section 7.2.177 |
Yes |
Yes |
Yes |
Sessions with sescase of |
Node-Functionality |
32.299 v12.11.0 section 7.2.113 |
Yes |
Yes |
Yes |
Set to value |
User-Session-Id |
32.299 v12.11.0 section 7.2.242 |
Yes |
Yes |
Yes |
Set to the Call-Id for the initial request |
Outgoing-Session-Id |
32.299 v12.11.0 section 7.2.128A |
No |
No |
No |
|
Session-Priority |
29.229 |
Yes |
Yes |
Yes |
Set to value |
Calling-Party-Address |
32.299 v12.11.0 section 7.2.33 |
Yes |
Yes |
Yes |
|
Called-Party-Address |
32.299 v12.11.0 section 7.2.32 |
Yes |
Yes |
Yes |
|
Called-Asserted-Identity |
32.299 v12.11.0 section 7.2.31 |
Yes |
Yes |
Yes |
|
Number-Portability-Routing-Information |
32.299 v12.11.0 section 7.2.120 |
No |
No |
No |
|
Carrier-Select-Routing-Information |
32.299 v12.11.0 section 7.2.34 |
No |
No |
No |
|
Alternate-Charged-Party-Address |
32.299 v12.11.0 section 7.2.12 |
No |
No |
No |
|
Requested-Party-Address |
32.299 v12.11.0 section 7.2.176 |
Yes |
Yes |
Yes |
This field is only included if different from the |
Associated-URI |
32.299 v12.11.0 section 7.2.26 |
No |
No |
No |
|
Application-Server-Information |
32.299 v12.11.0 section 7.2.24 |
No |
No |
No |
|
Inter-Operator-Identifier |
32.299 v12.11.0 section 7.2.80 |
Yes |
Yes |
Yes |
|
Transit-IOI-List |
32.299 v12.11.0 section 7.2.233B |
No |
No |
No |
|
IMS-Charging-Identifier |
32.299 v12.11.0 section 7.2.75 |
Yes |
Yes |
Yes |
|
SDP-Session-Description |
32.299 v12.11.0 section 7.2.184 |
Yes |
Yes |
Yes |
|
SDP-Media-Component |
32.299 v12.11.0 section 7.2.180 |
Yes |
Yes |
Yes |
|
Served-Party-IP-Address |
32.299 v12.11.0 section 7.2.187 |
No |
No |
No |
|
Server-Capabilities |
29.229 |
No |
No |
No |
|
Trunk-Group-ID |
32.299 v12.11.0 section 7.2.237 |
No |
No |
No |
|
Bearer-Service |
32.299 v12.11.0 section 7.2.30 |
No |
No |
No |
|
Service-Id |
32.299 v12.11.0 section 7.2.190 |
No |
No |
No |
|
Service-Specific-Info |
32.299 v12.11.0 section 7.2.195 |
No |
No |
No |
|
Message-Body |
32.299 v12.11.0 section 7.2.103 |
No |
No |
No |
|
Cause-Code |
32.299 v12.11.0 section 7.2.35 |
Yes |
Yes |
Yes |
|
Reason-Header |
32.299 v12.11.0 section 7.2.164A |
No |
No |
No |
|
Access-Network-Information |
32.299 v12.11.0 section 7.2.1 |
Yes |
Yes |
Yes |
The first value in the SIP P-Access-Network-Info header is included as the value for this AVP |
Early-Media-Description |
32.299 v12.11.0 section 7.2.58 |
Yes |
Yes |
Yes |
The most recent Early Media offer/answer is included |
IMS-Communication-Service-Identifier |
32.299 v12.11.0 section 7.2.76 |
Yes |
Yes |
Yes |
|
IMS-Application-Reference-Identifier |
32.299 v12.11.0 section 7.2.74A |
No |
No |
No |
|
Online-Charging-Flag |
32.299 v12.11.0 section 7.2.122 |
No |
No |
No |
|
Real-Time-Tariff-Information |
32.299 v12.11.0 section 7.2.164 |
No |
No |
No |
|
Account-Expiration |
32.299 v12.11.0 section 7.2.2 |
No |
No |
No |
|
Initial-IMS-Charging-Identifier |
32.299 v12.11.0 section 7.2.79A |
No |
No |
No |
|
NNI-Information |
32.299 v12.11.0 section 7.2.112A |
No |
No |
No |
|
From-Address |
32.299 v12.11.0 section 7.2.67A |
No |
No |
No |
|
IMS-Emergency-Indicator |
32.299 v12.11.0 section 7.2.76A |
No |
No |
No |
|
IMS-Visited-Network-Identifier |
32.299 v12.11.0 section 7.2.77A |
No |
No |
No |
|
Access-Transfer-Information |
32.299 v12.11.0 section 7.2.1A |
No |
No |
No |
|
Related-IMS-Charging-Identifier |
32.299 v12.11.0 section 7.2.171B |
No |
No |
No |
|
Related-IMS-Charging-Identifier-Node |
32.299 v12.11.0 section 7.2.171C |
No |
No |
No |
|
Route-Header-Received |
32.299 v12.11.0 section 7.2.177A |
No |
No |
No |
|
Route-Header-Transmitted |
32.299 v12.11.0 section 7.2.177B |
No |
No |
No |
|
Instance-Id |
32.299 v12.11.0 section 7.2.70A |
No |
No |
No |
|
TAD-Identifier |
32.299 v12.11.0 section 7.2.219A |
No |
No |
No |
The BNF syntax for the IMS-Information AVP according to 3GPP TS 32.299 v12.11.0 is as follows
IMS-Information :: = < AVP Header: 876> [ Event-Type ] [ Role-Of-Node ] { Node-Functionality } [ User-Session-Id ] [ Outgoing-Session-Id ] [ Session-Priority ] * [ Calling-Party-Address ] [ Called-Party-Address ] * [ Called-Asserted-Identity ] [ Number-Portability-Routing-Information ] [ Carrier-Select-Routing-Information ] [ Alternate-Charged-Party-Address ] * [ Requested-Party-Address ] * [ Associated-URI ] [ Time-Stamps ] * [ Application-Server-Information ] * [ Inter-Operator-Identifier ] * [ Transit-IOI-List ] [ IMS-Charging-Identifier ] * [ SDP-Session-Description ] * [ SDP-Media-Component ] [ Served-Party-IP-Address ] [ Server-Capabilities ] [ Trunk-Group-ID ] [ Bearer-Service ] [ Service-Id ] * [ Service-Specific-Info ] * [ Message-Body ] [ Cause-Code ] * [ Reason-Header ] * [ Access-Network-Information ] * [ Early-Media-Description ] [ IMS-Communication-Service-Identifier ] [ IMS-Application-Reference-Identifier ] [ Online-Charging-Flag ] [ Real-Time-Tariff-Information ] [ Account-Expiration ] [ Initial-IMS-Charging-Identifier ] * [ NNI-Information ] [ From-Address ] [ IMS-Emergency-Indicator ] [ IMS-Visited-Network-Identifier ] * [ Access-Transfer-Information ] [ Related-IMS-Charging-Identifier ] [ Related-IMS-Charging-Identifier-Node ] [ Route-Header-Received ] [ Route-Header-Transmitted ] [ Instance-Id ] [TAD-Identifier]
Additional populated AVPs
This table lists additional standard AVPs that appear at the top level of a CDR or CCR instead of their standard place in a grouped AVP.
AVP Name | Specification reference | Included in CDR | Included in CCR | Comments |
---|---|---|---|---|
PDP-Address |
32.299 v12.11.0 section 7.2.137 |
No |
Yes |
Destination IPCAN address of SIP message |
Populated OpenCloud AVPs
The population of OpenCloud AVPs is described here. The definition of OpenCloud AVPs is provided in Sentinel AVP definitions. ACRs are not used by Sentinel IPSMGW.
AVP Name | Specification reference | Included in CDR | Included in CCR | Included in ACR | Comments |
---|---|---|---|---|---|
OC-Sentinel-Selection-Key |
Yes |
No |
Yes |
n/a |
|
OC-Play-Announcement-Id |
Yes |
No |
Yes |
n/a |
|
OC-Call-Type |
Yes |
No |
Yes |
Role-Of-Node AVP has similar meaning on the Ro interface |
|
OC-Service-Type |
Yes |
No |
Yes |
n/a |
|
OC-Charging-Result |
Yes |
No |
Yes |
||
OC-OCS-Session-Id |
Yes |
No |
Yes |
This is the session ID in Ro |
|
OC-OCS-Session-Termination-Cause |
Yes |
No |
Yes |
||
OC-Sentinel-Error |
Yes |
No |
Yes |
||
OC-Charging-Instance |
Yes |
No |
Yes |
||
OC-Event-Id |
Yes |
No |
Yes |
||
OC-Call-Id |
Yes |
No |
Yes |
The Ro Session Id optional part includes the SIP Call ID |
|
OC-End-Session-Cause |
Yes |
No |
Yes |
||
OC-Start-Time |
Yes |
No |
Yes |
||
OC-End-Time |
Yes |
No |
Yes |
||
OC-Session-Start-Time |
Yes |
No |
Yes |
||
OC-Session-Established-Time |
Yes |
No |
Yes |
Included if an INVITE session is answered |
|
OC-Session-End-Time |
Yes |
No |
Yes |
||
OC-Session-Counter |
Yes |
No |
Yes |
||
OC-Interim-CDR-Trigger |
Yes |
No |
Yes |
||
OC-Access-Network-MCC-MNC |
Yes |
Yes |
Yes |
||
OC-Visited-Network-MCC-MNC |
Yes |
Yes |
Yes |
||
OC-IMSI-MCC-MNC |
Yes |
Yes |
Yes |
||
OC-Session-Failover-Detected |
Yes |
Yes |
Yes |
||
OC-SM-Message-Type |
Yes |
Yes |
n/a |
n/a |
|
OC-Plan-Id |
Yes |
No |
n/a |
n/a |
|
OC-Submit-Report-Type |
Yes |
No |
n/a |
n/a |
|
OC-MT-Correlated-Id |
Yes |
No |
n/a |
n/a |
|
OC-MT-PS-Delivery-Result |
Yes |
No |
n/a |
n/a |
|
OC-MT-CS-Delivery-Result |
Yes |
No |
n/a |
n/a |
|
OC-IMPU |
Yes |
No |
n/a |
n/a |
Sentinel AVP definitions
The following AVPs are OpenCloud defined AVPs used that are used in the Sentinel IPSMGW product. All OpenCloud defined AVPs have a diameter vendor ID of 19808.
AVPs defined in the Sentinel IPSMGW product
The Sentinel IPSMGW product extends Sentinel Express and adds the following AVP.
OC-SM-Message-Type
The OC-SM-Message-Type AVP (AVP code 2007) is of type Enumerated. It is set based on the MT ForwardSM TPDU Type. This is an OpenCloud defined AVP, as the standardized SM-Message-Type
AVP in 3GPP TS 32.274 v8.2.0 does not allow MT values.
-
SUBMISSION
= 0 -
DELIVERY_REPORT
= 1 -
STATUS_REPORT
= 100 -
DELIVER
= 101
No Parent AVP.
OC-Plan-Id
The OC-Plan-Id AVP (AVP code 1030) is of type UTF8String. It contains the PlanId for the session. Refer to the DetermineSessionPlan feature for more information on how this is set.
OC-Submit-Report-Type
OC-Submit-Report-Type AVP (AVP code 1031) is of type Enumerated. It contains the submit report type for the MOFSM
PlanId.
It can be one of the following:
-
NOT_APPLICABLE
= 1 -
SUCCESS
= 2 -
INVALID_SMS
= 3 -
COMMUNICATION_ERROR
= 4 -
U_ABORT
= 5 -
P_ABORT
= 6 -
INVOKE_TIMEOUT
= 7 -
MO_FORWARD_SM_ERROR
= 8 -
SS7_STACK_ERROR
= 9
No Parent AVP.
OC-MT-Correlated-Id
The OC-MT-Correlated-Id AVP (AVP code 1032) is of type UTF8String. It contains the MT-Correlation-Id associated with the session IMSI.
OC-MT-PS-Delivery-Result
OC-MT-PS-Delivery-Result AVP (AVP code 1033) is of type Enumerated and specifies the PS-Delivery status.
It can be one of the following:
-
NOT_ATTEMPTED
= 1 -
DELIVERY_SUCCEEDED
= 2 -
DELIVERY_FAILED
= 3
No Parent AVP.
AVPs defined in Sentinel Express
The following AVPs are defined in the Sentinel Express product, and are used in the Sentinel IPSMGW product.
OC-Sentinel-Selection-Key
The OC-Sentinel-Selection-Key AVP (AVP code 1001) is of type UTF8String and contains the Sentinel Selection Key for the session.
No Parent AVP.
OC-Play-Announcement-Id
The OC-Play-Announcement-Id AVP (AVP code 1002) is of type Integer32 and contains the ID of an announcement used during the session.
No Parent AVP.
OC-Call-Type
The OC-Call-Type AVP (AVP code 1003) is of type Enumerated and specifies the type of trigger for the session.
It can be one of the following:
-
MOC
= 1, the trigger was Originating -
MOC_3RDPTY
= 2, the trigger was a non-SIP third party call setup request (e.g. via HTTP) -
MTC
= 3, the trigger was Terminating -
MFC
= 4, the trigger was Forwarding -
EMERGENCY_CALL
= 9, the trigger was classified as emergency
No Parent AVP.
OC-Service-Type
The OC-Service-Type AVP (AVP code 1004) is of type Enumerated and specifies the initiating message for the session.
It can be one of the following:
-
UNKNOWN
= 1, the initiating reason is unknown -
SipCall
= 2, the session was initiated due to receipt of SIP INVITE -
Subscription
= 3, the session was initiated due to receipt of SIP SUBSCRIBE -
Message
= 5, the session was initiated due to receipt of SIP MESSAGE
No Parent AVP.
OC-Charging-Result
The OC-Charging-Result AVP (AVP code 1006) is of type Integer32. It contains the value of the Diameter CCA result-code AVP. In case there was no Ro session, it will have the value of -1.
No Parent AVP.
OC-OCS-Session-Id
The OC-OCS-Session-Id AVP (AVP code 1008) is of type UTF8String. It indicates a Session Id used to communicate with the OCS during the session.
No Parent AVP.
OC-OCS-Session-Termination-Cause
The OC-OCS-Session-Termination-Cause AVP (AVP code 1009) is of type Integer32. It communicates the reason that the OCS (or mediation layer) terminated the Ro session. It can be one of the following:
-
NORMAL_SESSION_COMPLETION
= 0, the session terminated normally. -
ERROR_CCA
= 1, the session was terminated due to a CCA error response. -
CREDIT_LIMIT_REACHED
= 2, the session was terminated due to Credit-Limit-Reached. -
OCS_ABORT
= 3, the session was terminated due to an ASR received from the OCS. -
TCC_EXPIRED
= 4, the session was terminated due to the Sentinel Tcc timer expiring. -
CREDIT_CONTROL_FAILURE
= 5, the session was terminated due to a failure generating CCR. -
CLIENT_ABORT
= 6, the session terminated due to a client request, typically as a result of an abnormal event.
No Parent AVP.
OC-Sentinel-Error
The OC-Sentinel-Error AVP (AVP code 1010) is of type Enumerated.
It can be one of the following:
-
None
= 1 -
OcsTimeout
= 2 -
OcsCommunicationFailure
= 3 -
SentinelOverload
= 4 -
ProtocolError
= 5 -
InternalError
= 6 -
MappingError
= 7 -
OtherError
= 8
If there is a Credit Control Answer, and it has an Experimental Result Code, and that has an OpenCloud vendor ID, then this AVP is filled.
No Parent AVP.
OC-Charging-Instance
The OC-Charging-Instance AVP (AVP code 1011) is of type Grouped. An OC-Charging-Instance AVP represents an online charging instance used during the session.
OC-Charging-Instance ::= < AVP Header: 1011 > [ OC-Charging-Instance-Name ] *[ OC-Session-Counter ]
No Parent AVP.
OC-Charging-Instance-Name
The OC-Charging-Instance-Name AVP (AVP code 1012) is of type UTF8String. It represents the name of an OC-Charging-Instance.
Parent AVP: OC-Charging-Instance
OC-Session-Counter
The OC-Session-Counter AVP (AVP code 1013) is of type Grouped. It represents a Session Counter used during the session.
Parent AVP: OC-Charging-Instance
OC-Session-Counter ::= < AVP Header: 1013 > *[ OC-Session-Counter-Address ] [ OC-Cumulative-Committed-Used ] [ OC-Cumulative-Granted ] [ OC-Cumulative-Granted-Refund ] [ OC-Cumulative-Requested ] [ OC-Cumulative-Requested-Refund ] [ OC-Cumulative-Sent-Used ] [ OC-Cumulative-Suspended-Duration ] [ OC-Reported-Used ] [ OC-End-Time ] [ OC-Pending-Requested ] [ OC-Start-Time ]
OC-Session-Counter-Address
The OC-Session-Counter-Address AVP (AVP code 1014) is of type Grouped. It represents a Session Counter address
field, as documented in Session counter structure.
OC-Session-Counter-Address ::= < AVP Header: 1014 > [ OC-Session-Counter-Address-Key ] [ OC-Session-Counter-Address-Value ]
Parent AVP: OC-Session-Counter
OC-Session-Counter-Address-Key
The OC-Session-Counter-Address-Key AVP (AVP code 1015) is of type UTF8String.
Parent AVP: OC-Session-Counter-Address
OC-Session-Counter-Address-Value
The OC-Session-Counter-Address-Value AVP (AVP code 1016) is of type UTF8String.
Parent AVP: OC-Session-Counter-Address
OC-Cumulative-Committed-Used
The OC-Cumulative-Committed-Used AVP (AVP code 1017) is of type Integer64.
It contains the value of the cumulativeCommittedUsed
unit counter documented in Session counter structure.
Parent AVP: OC-Session-Counter
OC-Cumulative-Granted
The OC-Cumulative-Granted AVP (AVP code 1018) is of type Integer64.
It contains the value of the cumulativeGranted
unit counter documented in Session counter structure.
Parent AVP: OC-Session-Counter
OC-Cumulative-Granted-Refund
The OC-Cumulative-Granted-Refund AVP (AVP code 1019) is of type Integer64.
It contains the value of the cumulatedGrantedRefund
unit counter documented in Session counter structure.
Parent AVP: OC-Session-Counter
OC-Cumulative-Requested
The OC-Cumulative-Request AVP (AVP code 1020) is of type Integer64.
It contains the value of the cumulatedRequested
unit counter documented in Session counter structure.
Parent AVP: OC-Session-Counter === OC-Cumulative-Requested-Refund
The OC-Cumulative-Requested-Refund AVP (AVP code 1021) is of type Integer64.
It contains the value of the cumulativeRequestedRefund
unit counter documented in Session counter structure.
Parent AVP: OC-Session-Counter
OC-Cumulative-Sent-Used
The OC-Cumulative-Sent-Used AVP (AVP code 1022) is of type Integer64. It contains the cumulative used units sent to the OCS for the Session Counter.
It contains the value of the cumulativeSentUsed
unit counter documented in Session counter structure.
Parent AVP: OC-Session-Counter
OC-Cumulative-Suspended-Duration
The OC-Cumulative-Suspended-Duration AVP (AVP code 1023) is of type Integer64.
It contains the value of the cumulativeSuspendedDuration
field documented in Session counter structure.
Parent AVP: OC-Session-Counter
OC-Reported-Used
The OC-Reported-Used AVP (AVP code 1024) is of type Integer64.
It contains the value of the reportedUsed
field documented in Session counter structure.
Parent AVP: OC-Session-Counter
OC-Pending-Requested
The OC-Pending-Requested AVP (AVP code 1025) is of type Integer64.
It contains the value of the pendingRequested
unit counter documented in Session counter structure.
Parent AVP: OC-Session-Counter
OC-Start-Time
The OC-Start-Time AVP (AVP code 1026) is of type Time.
It contains the value of the startTime
field documented in Session counter structure.
Parent AVP: OC-Session-Counter
OC-End-Time
The OC-End-Time AVP (AVP code 1027) is of type Time.
It contains the value of the endTime
field documented in Session counter structure.
Parent AVP: OC-Session-Counter
OC-Event-Id
The OC-Event-Id AVP (AVP code 1028) is of type UTF8String.
If the initial request for the Session was a SIP SUBSCRIBE
or SIP NOTIFY
request, this is set to the value of the Event:
header in the initial request.
If the initial request for the Session was a SIP REFER
request, this is set to the CSeq
of the REFER request.
No parent AVP.
OC-Call-Id
The OC-Call-Id AVP (AVP code 1029) is of type UTF8String. This is set to the Call-ID of the initial SIP request for the Session.
No parent AVP.
OC-End-Session-Cause
The OC-End-Session-Cause AVP (AVP code 1036) is of type Integer32. This is set to indicate the reason a service or feature ended the session.
If the LegManager.endSession
instruction is called with a cause value, the AVP value is set to the cause value.
Otherwise, if the session state field endSessionCause
is set, the AVP value is set to the session state value.
No parent AVP.
OC-Interim-CDR-Trigger
The OC-Interim-CDR-Trigger AVP (AVP code 1037) is a repeated AVP of type Grouped and appears only in interim CDRs. Each occurrence indicates a reason and a supplementary reason for writing an Interim CDR and the leg for which the reasons apply.
OC-Interim-CDR-Trigger ::= < AVP Header: 1037 > [ OC-Interim-CDR-Reason ] [ OC-Interim-CDR-Supplementary-Reason] [ OC-Interim-CDR-Leg ]
No parent AVP.
OC-Interim-CDR-Reason
The OC-Interim-CDR-Reason AVP (AVP code 1038) is of type UTF8String.
Parent AVP: OC-Interim-CDR-Trigger
OC-Interim-CDR-Leg
The OC-Interim-CDR-Leg AVP (AVP code 1039) is of type UTF8String.
Parent AVP: OC-Interim-CDR-Trigger
OC-Session-Start-Time
The OC-Session-Start-Time AVP (AVP code 1040) is of type Time.
It contains the time that the session’s Initial Request was processed.
No parent AVP.
OC-Session-Established-Time
The OC-Session-Established-Time AVP (AVP code 1041) is of type Time.
It contains the time that the session was answered, that is the ACK to the 2xx-INVITE was processed.
No parent AVP.
OC-Session-End-Time
The OC-Session-End-Time AVP (AVP code 1042) is of type Time.
It contains the time that the session was ended.
No parent AVP.
OC-Interim-CDR-Supplementary-Reason
The OC-Interim-CDR-Supplementary-Reason AVP (AVP code 1043) is of type UTF8String.
Parent AVP: OC-Interim-CDR-Trigger
OC-Age-Of-Information
The OC-Age-Of-Information AVP (AVP code 1060) is of type Integer64. The time in milliseconds of the source information. The value depends on which of the grouped AVP’s contains the OC-Age-Of-Information.
OC-MCC-MNC
The OC-MCC-MNC AVP (AVP code 1061) is of type UTF8String. The length is 5 or 6 digits depending on the value of MNC, that can be 2 or 3. It is encoded as UTF8String characters representing the IMSI MCC-MNC numerical values. In accordance with 3GPP TS 29.060 24 (for GGSN), 3GPP TS 29.274 81 (for P-GW) and 3GPP TS 23.003 40, the MCC is 3 digits and the MNC is either 2 or 3 digits. There are no padding characters between the MCC and MNC.
OC-Access-Network-MCC-MNC
The OC-Access-Network-MCC-MNC (AVP code 1062) indicates the home network MCC-MNC, in case the access network can be identified. The information is extracted from the P-Access-Network-Info header. It is a grouped AVP formed by:
-
OC-MCC-MNC
-
OC-Age-Of-Information
The OC-Age-Of-Information is the registration time.
No parent AVP.
OC-Visited-Network-MCC-MNC
The OC-Visited-Network-MCC-MNC (AVP code 1063) indicates the visited network MCC-MNC, in case the visited network can be identified. This information is extracted from the P-Visited-Network-Id header. It is a grouped AVP formed by:
-
OC-MCC-MNC
-
OC-Age-Of-Information
The OC-Age-Of-Information is the registration time.
No parent AVP.
OC-IMSI-MCC-MNC
The OC-IMSI-MCC-MNC (AVP code 1064) is extracted from the IMSI and indicates the network related to the subscriber IMSI. It is a grouped AVP formed by:
-
OC-MCC-MNC
-
OC-Age-Of-Information
The OC-Age-Of-Information is:
-
registration time
-
SRI response time in case it is extracted from the SRI response.
No parent AVP.
OC-Session-Failover-Detected
The OC-Session-Failover-Detected (AVP code 1066) flag indicates whether a session failover occured between the initial event and when this AVP was written.
It is of type Integer32, with the value '0' indicating that session failover has not been detected and '1' indicating session failover has been detected.
No parent AVP.
Ro Interface AVPs
The AVPs used by Sentinel IPSMGW in the credit control request are described.
Sentinel IPSMGW Service population of Credit Control Request
The Credit Control Request message is defined according to IETF RFC 4006, and some AVPs are removed and not used according to 3GPP TS 32.299. Sentinel products use the definition in 3GPP TS 32.299 v12.11.0 for CCR.
This table indicates the top-level AVPs inside a CCR request and how the Sentinel SIP service populates them.
AVP Name | Specification reference | Included in CDR | Included in CCR | Comments |
---|---|---|---|---|
Service-Context-Id |
IETF RFC 4006 and refined by 3GPP TS 32.299 v12.11.0 section 7.1.12 |
Yes |
Yes |
For IP-SM-GW the value is set to |
Session-Id |
IETF RFC 4006 |
Yes |
Yes |
The Session-Id optional part is set to the Call-ID of the initial request for the Session |
Origin-Host |
IETF RFC 4006 |
No |
Yes |
Resource Adaptor entity configuration defines the value to be used for this AVP |
Origin-Realm |
IETF RFC 4006 |
No |
Yes |
Resource Adaptor entity configuration defines the value to be used for this AVP |
Destination-Realm |
IETF RFC 4006 |
No |
Yes |
This is set in Sentinel configuration, when selecting an OCS to use for the Session |
Auth-Application-Id |
IETF RFC 4006 |
No |
Yes |
Set to the value |
Service-Context-Id |
IETF RFC 4006 |
Yes |
Yes |
|
CC-Request-Type |
IETF RFC 4006 |
No |
Yes |
|
CC-Request-Number |
IETF RFC 4006 |
No |
Yes |
|
Destination-Host |
IETF RFC 4006 |
No |
No |
|
Origin-State-Id |
IETF RFC 4006 |
No |
No |
|
Event-Timestamp |
IETF RFC 4006 |
No |
Yes |
|
Subscription-Id |
IETF RFC 4006 |
Yes |
Yes |
Set to the Served User, either as a SIP URI or Tel URI. This is populated via the SIP Subscriber Determination Feature. |
Termination-Cause |
IETF RFC 3588 |
No |
No |
|
Requested-Action |
IETF RFC 4006 |
No |
Yes |
|
AoC-Request-Type |
IETF RFC 4006 |
No |
No |
|
Multiple-Services-Indicator |
IETF RFC 4006 |
No |
Yes |
Set to |
Multiple-Services-Credit-Control |
IETF RFC 4006 |
Yes |
Yes |
In the case of AVP CDRs, if Ro charging is used then MSCC AVPs from the most recent CCA are written to the CDR. In the case of Ro charging the CCR’s MSCC AVP includes Populated AVPs in the Multiple-Services-Credit-Control AVP |
CC-Correlation-Id |
IETF RFC 4006 |
No |
No |
|
User-Equipment-Info |
IETF RFC 4006 |
Yes |
Yes |
The IMEI is used rather than the IMEISV, and the User-Equipment-Type AVP is set to IMEISV. |
Proxy-Info |
IETF RFC 4006 |
No |
No |
|
Route-Record |
IETF RFC 4006 |
No |
No |
|
Service-Information |
3GPP TS 32.299 |
No |
Yes |
Refer to Populated AVPs in the Service-Information AVP ## in volte documentation |
User-Name |
IETF RFC 6733 |
Yes |
Yes |
This contains the Private Id from registration data |
The BNF for the CCR message according to 32.299 v12.11.0 is
<CCR> ::= < Diameter Header: 272, REQ, PXY > < Session-Id > { Origin-Host } { Origin-Realm } { Destination-Realm } { Auth-Application-Id } { Service-Context-Id } { CC-Request-Type } { CC-Request-Number } [ Destination-Host ] [ User-Name ] [ CC-Sub-Session-Id ] // not used in 3GPP [ Acct-Multi-Session-Id ] // not used in 3GPP [ Origin-State-Id ] [ Event-Timestamp ] *[ Subscription-Id ] [ Service-Identifier ] // not used in 3GPP [ Termination-Cause ] [ Requested-Service-Unit ] // not used in 3GPP [ Requested-Action ] *[ Used-Service-Unit ] // not used in 3GPP [ AoC-Request-Type ] [ Multiple-Services-Indicator ] *[ Multiple-Services-Credit-Control ] *[ Service-Parameter-Info ] // not used in 3GPP [ CC-Correlation-Id ] [ User-Equipment-Info ] *[ Proxy-Info ] *[ Route-Record ] [ Service-Information ] *[ AVP ]
Sizing AVP CDRs
This section documents the storage requirements for AVP CDRs.
Binary CDR log structure
Each CDR log file can be broken down into the following parts:
-
Protobuf overhead - a small amount of type information about contained records.
-
A header section - a small amount of data written by the CDR RA including version, host, and timestamp information.
-
Zero or more AVP CDRs - these records will vary in individual size, and usually form the majority of a CDR log.
-
A footer - this is empty for Sentinel products.
Sizing analysis
The combined size of the header, footer, and protobuf overhead is normally trivial (<1KB) compared to the size of each finished CDR log file.
Individual CDR records will vary in size based on dynamic content such as hostnames, Sentinel selection key names, SDP content, and other similarly variable character data. As such, it is not possible to provide exact sizing for a given system without examining the CDR logs written while under a test load, but some approximations can be made.
A basic CDR record containing the information normally written by Sentinel will be on the order of 2000-3000 bytes. With this in mind, the following sections provide rough estimates regarding how much storage would be required for specific scenarios.
If Sentinel is configured to write Session CDRs (i.e. not writing Interim CDRs), then each session will write a single CDR on the order of 2000-3000 bytes.
Working with CDRs
Sentinel writes binary CDRs using the CDR RA. Refer to CDR Resource Adaptor section of this guide for more information about Sentinel and the CDR RA. |
List CDRs
The Sentinel SDK contains a List CDRs tool, which can be used to print Sentinel’s binary CDRs files to a human readable format.
The CDR files contain binary encoded Diameter AVPs files in addition to a header and footer. The List CDRs tool decodes the binary CDR file and all the Diameter AVPs which is contains, printing them to the console.
It also supports printing the older 'legacy' CDR format which is not based on AVPs, as used by Sentinel version 2.4.x and earlier.
How to use it in a nutshell:
-
Install the SDK normally using the SDK installer script, which will automatically install list-cdrs at
ipsmgw-sdk/tools/list-cdrs
-
Run
ipsmgw-sdk/tools/list-cdrs/list-cdrs.sh CDRFILE1 [CDRFILE2]…
This guide covers the installation options and customisation options available for List CDRs.
Protobuf
Protobuf 2.3.0 is required to build and extend CDR modules included with the SDK. This guide covers installing Protobuf for use with the SDK. If using the product "out of the box", Protobuf is not required.
Topics
-
Installing List CDRs — describes how to install the List CDRs tool
-
Obtaining CDRs — describes how to obtain CDRs used as input to the List CDRs tool
-
Running List CDRs — describes how to run the List CDRs tool
-
Extension AVPs — describes how to configure extension AVPs in the List CDRs tool
-
Installing Protobuf — describes how to install Protobuf
Installing List CDRs
Installing the List CDRs tools using the SDK installer
If you install the SDK using the ipsmgw-sdk/build/bin/installer
script, then the installer will automatically install the list-cdrs tool at /home/testuser/ipsmgw-sdk/list-cdrs/
.
$ ./build/bin/installer [...] Creating deployment module deploy-volte ... done. [...] Configuration changes written. [...] Installing List CDRs tool ... done. [...]
Installing List CDRs from the SDK using Ant
To install the List CDRs tool using the Ant script instead, use the install-list-cdrs
Ant build target under the ipsmgw-sdk/tools
directory:
$ cd /home/testuser/ipsmgw-sdk/tools $ ant install-list-cdrs Buildfile: /home/testuser/ipsmgw-sdk/tools/build.xml init-build-extensions: [...] install-list-cdrs: [echo] [echo] Retrieving List CDRs... [ivy:resolve] downloading https://{download-link-host}/artifactory/opencloud-internal-snapshots/opencloud/sentinel-core/3.1.0/sentinel-list-cdrs/3.1.0.0/sentinel-list-cdrs-package-3.1.0.0.zip ... [ivy:resolve] ..... (8971kB) [ivy:resolve] .. (0kB) [ivy:resolve] [SUCCESSFUL ] opencloud#sentinel-list-cdrs#sentinel-core/3.1.0;3.1.0.0!sentinel-list-cdrs-package.zip (1143ms) [echo] [echo] List CDRs retrieved. [echo] [echo] Installing List CDRs ... [echo] [unzip] Expanding: /home/testuser/ipsmgw-sdk/tools/target/sentinel-list-cdrs-package.zip into /home/testuser/ipsmgw-sdk/tools [echo] [echo] [echo] List CDRs installed. [echo] To print CDR files, use the script at list-cdrs/list-cdrs.sh [echo] Usage: list-cdrs CDRFILE [CDRFILE]... [echo] BUILD SUCCESSFUL Total time: 14 seconds
See Setting up Ant in the Sentinel IP-SM-GW SDK guide. |
Installing List CDRs Standalone
The above two approaches are automated ways of installing the List CDRs package (sentinel-list-cdrs-package.zip
) into a particular location: ipsmgw-sdk/tools/list-cdrs/
.
Both the above methods place a List CDRs installer archive at ipsmgw-sdk/tools/target/sentinel-list-cdrs-package.zip
.
This sentinel-list-cdrs-package.zip
archive can be moved to and unzipped into another location outside of the SDK and used as a standalone tool.
To install the List CDRs package as a standalone tool, simply unzip the sentinel-list-cdrs-package.zip
archive to your chosen destination directory.
The mechanisms for invoking and configuration the List CDRs tools are the same as when running the tool inside the SDK. Simply substitute /home/testuser/ipsmgw-sdk/tools/list-cdrs
with /your/chosen/directory/list-cdrs
.
Uninstalling List CDRs
If you want to uninstall the List CDRs tool, use the uninstall-list-cdrs
Ant target under the ipsmgw-sdk/tools
directory:
$ cd /home/testuser/ipsmgw-sdk/tools $ ant uninstall-list-cdrs Buildfile: /home/testuser/ipsmgw-sdk/tools/build.xml uninstall-list-cdrs: [echo] Uninstalling (deleting) the list-cdrs install from: /home/testuser/ipsmgw-sdk/tools/list-cdrs/ [delete] Deleting directory /home/testuser/ipsmgw-sdk/tools/list-cdrs BUILD SUCCESSFUL Total time: 0 seconds
Alternatively, just delete the list-cdrs
directory:
$ rm -rf ipsmgw-sdk/tools/list-cdrs/
Obtaining CDRs
Obtaining CDR files
The List CDRs tool is designed to read completed binary CDR files generated by Sentinel.
Sentinel uses the CDR RA to write CDR files in a binary format. It typically writes these CDR files to the cdr
directory inside the Rhino installation, and writes these binary CDR files using names such as cdr_101_1468259745367.log
.
The List CDRs tool can read these completed binary CDR files either in their raw binary format (e.g. cdr_101_1468259745367.log
), or in gzip compressed format (e.g. cdr_101_1468259745367.log.gz
).
Before a CDR file is completed, Sentinel may write a partial CDR file to disk, e.g. cdr_101_cdr-stream_28929467492591509.tmp . When a partially written CDR is ready to be rolled over, the CDR RA converts it to a completed binary CDR file, e.g. cdr_101_1468259745367.log . The List CDRs tool cannot read partially written CDR files. It can only read complete CDR files. |
Running List CDRs
To invoke the List CDRs tool, run the list-cdrs.sh
script under the ipsmgw-sdk/tools/list-cdrs
directory. Pass one or more file paths as arguments, each being a path to a completed binary CDR file generated by Sentinel.
If the ipsmgw-sdk/tools parent directory does not contain a list-cdrs directory, then the List CDRs tool needs to be installed. The Installing List CDRs page describes how to install the List CDRs tool. |
Calling the script with no arguments shows the expected syntax:
$ ./tools/list-cdrs/list-cdrs.sh Usage: list-cdrs.sh [--no-header] [--no-footer] [--no-protocol] [--ignore-error] [--output-file OUTPUTFILE] [--size-limit BYTES] [--cdr-filter FIELD=REGEX] CDRFILE [CDRFILE]... --no-header - Disable printing of CDR headers. --no-footer - Disable printing of CDR footers. --no-protocol - Disable printing of protocol and spec revisions in top level AVPs, e.g. "(Ro,vcb0)". --ignore-error - Continue processing CDRs files when encountering recoverable errors. --list-icids - List all unique IMS Charging Identifiers in the given CDR file(s), in order of first appearance. --filter-by-icid ICID - Print CDR message body only when CDR contains the given IMS Charging Identifier. ICID can be listed by "--list-icids" option. --output-file OUTPUTFILE - Append CDR output to OUTPUTFILE rather than to the console. --size-limit BYTES - CDR record size limit. Minimum and default value is 67108864 (64MB). Increase if encountering "Protocol message was too large" exception. --cdr-filter FIELD=REGEX - Print CDR message body only when the given FIELD matches the given regular expression. FIELD can be a field name, an AVP name, or an AVP path like "/IMS-Information/User-Session-Id". CDRFILE - A completed binary CDR file as produced by Sentinel. Both the new AVP based format (Sentinel 2.5 and later) and the older format (Sentinel 2.4 and earlier) are supported. CDR files can optionally be in gzip format, using a '.gz' suffix. Partially written CDR files (ending in ".tmp") are not supported.
An example invocation, showing how to print a CDR file:
2016-08-03T20:45:47.569+1200 Header { ra_name=CDR Generation, ra_vendor=OpenCloud, ra_version=2.3, ra_release=2.3.0.0, ra_build=20160715041441, ra_revision=cdr-ra/2.3.0@a177ef4, description=CDR session, rhino_node=101, ra_entity=cdr, hostname=stroganoff.opencloud.co.nz } 2016-08-03T20:45:47.575+1200 AvpCdr { avps=[ IMS-Information(Ro,vcb0)[ Node-Functionality[AS(6)], Session-Priority[PRIORITY_2(2)] ], Service-Context-Id(Ro,vcb0)[12.32274@3gpp.org], OC-Sentinel-Selection-Key(Ext,Ext)[DefinitelyNotOpenCloud:DefinitelyNotOpenCloud:map:SRI4SM:], OC-Service-Type(Ext,Ext)[Unknown(1)], OC-Charging-Result(Ext,Ext)[-1], OC-Sentinel-Error(Ext,Ext)[None(1)], OC-Plan-Id(Ext,Ext)[SRI4SM], OC-Submit-Report-Type(Ext,Ext)[NOT_APPLICABLE(1)], MSISDN(Ro,vcb0)[46 21 43 65 87], OC-MT-Correlated-Id(Ext,Ext)[001010000000000], OC-MT-PS-Delivery-Result(Ext,Ext)[NOT_ATTEMPTED(1)], OC-MT-CS-Delivery-Result(Ext,Ext)[NOT_ATTEMPTED(1)], SMS-Information(Ro,vcb0)[ Originator-SCCP-Address[00 08 53 63 63 70 41 64 64 72 65 73 73 5b 74 79 70 65 3d 43 37 2c 72 6f 75 74 65 4f 6e 44 50 43 3f 3d 66 61 6c 73 65 2c 6e 61 74 69 6f 6e 61 6c 55 73 65 3f 3d 74 72 75 65 2c 67 74 20 69 6e 64 69 63 61 74 6f 72 3d 47 54 5f 30 30 30 31 2c 6e 61 74 75 72 65 3d 33 20 28 6e 61 74 69 6f 6e 61 6c 20 28 73 69 67 6e 69 66 69 63 61 6e 74 29 20 6e 75 6d 62 65 72 29 2c 61 64 64 72 65 73 73 3d 36 34 31 32 33 5d], Recipient-Info[ Recipient-SCCP-Address[00 08 53 63 63 70 41 64 64 72 65 73 73 5b 74 79 70 65 3d 43 37 2c 72 6f 75 74 65 4f 6e 44 50 43 3f 3d 74 72 75 65 2c 6e 61 74 69 6f 6e 61 6c 55 73 65 3f 3d 74 72 75 65 2c 70 63 3d 36 20 28 30 2f 30 2f 36 29 2c 73 73 6e 3d 31 34 37 5d] ] ] ] } 2016-08-03T20:45:48.685+1200 AvpCdr { avps=[ IMS-Information(Ro,vcb0)[ Role-Of-Node[ORIGINATING_ROLE(0)], Node-Functionality[AS(6)], Session-Priority[PRIORITY_2(2)], Called-Party-Address[sip:127.0.0.1:5060], ], Service-Context-Id(Ro,vcb0)[12.32260@3gpp.org], OC-Sentinel-Selection-Key(Ext,Ext)[DefinitelyNotOpenCloud:DefinitelyNotOpenCloud:sipcall:MTFSM_DR:], OC-Call-Type(Ext,Ext)[MOC(1)], OC-Service-Type(Ext,Ext)[Message(5)], OC-Charging-Result(Ext,Ext)[-1], OC-Sentinel-Error(Ext,Ext)[None(1)], OC-Call-Id(Ext,Ext)[e-gJhCPjtEDqoZWG8yBIng], OC-Plan-Id(Ext,Ext)[MTFSM_DR], OC-Submit-Report-Type(Ext,Ext)[NOT_APPLICABLE(1)], OC-MT-PS-Delivery-Result(Ext,Ext)[NOT_ATTEMPTED(1)], OC-MT-CS-Delivery-Result(Ext,Ext)[NOT_ATTEMPTED(1)], SMS-Information(Ro,vcb0)[ ] ] } 2016-08-03T20:45:48.878+1200 AvpCdr { avps=[ IMS-Information(Ro,vcb0)[ Node-Functionality[AS(6)], Session-Priority[PRIORITY_2(2)] ], Service-Context-Id(Ro,vcb0)[12.32274@3gpp.org], OC-Sentinel-Selection-Key(Ext,Ext)[DefinitelyNotOpenCloud:DefinitelyNotOpenCloud:map:MTFSM_PS_CS:], OC-Service-Type(Ext,Ext)[Unknown(1)], OC-Charging-Result(Ext,Ext)[-1], OC-Sentinel-Error(Ext,Ext)[None(1)], OC-End-Session-Cause(Ext,Ext)[202], OC-Plan-Id(Ext,Ext)[MTFSM_PS_CS], OC-Submit-Report-Type(Ext,Ext)[NOT_APPLICABLE(1)], MSISDN(Ro,vcb0)[46 21 43 65 87], TGPP-IMSI(Ro,vcb0)[001010000001001], OC-MT-Correlated-Id(Ext,Ext)[001010000000000], OC-MT-PS-Delivery-Result(Ext,Ext)[DELIVERY_SUCCEEDED(2)], OC-MT-CS-Delivery-Result(Ext,Ext)[NOT_ATTEMPTED(1)], OC-IMPU(Ext,Ext)[tel:+6412345678], SMS-Information(Ro,vcb0)[ Originator-SCCP-Address[00 08 53 63 63 70 41 64 64 72 65 73 73 5b 74 79 70 65 3d 43 37 2c 72 6f 75 74 65 4f 6e 44 50 43 3f 3d 66 61 6c 73 65 2c 6e 61 74 69 6f 6e 61 6c 55 73 65 3f 3d 74 72 75 65 2c 67 74 20 69 6e 64 69 63 61 74 6f 72 3d 47 54 5f 30 30 30 31 2c 6e 61 74 75 72 65 3d 33 20 28 6e 61 74 69 6f 6e 61 6c 20 28 73 69 67 6e 69 66 69 63 61 6e 74 29 20 6e 75 6d 62 65 72 29 2c 61 64 64 72 65 73 73 3d 36 34 31 32 33 5d], Recipient-Info[ Recipient-SCCP-Address[00 08 53 63 63 70 41 64 64 72 65 73 73 5b 74 79 70 65 3d 43 37 2c 72 6f 75 74 65 4f 6e 44 50 43 3f 3d 74 72 75 65 2c 6e 61 74 69 6f 6e 61 6c 55 73 65 3f 3d 74 72 75 65 2c 70 63 3d 36 20 28 30 2f 30 2f 36 29 2c 73 73 6e 3d 31 34 37 5d] ] ] ] } 2016-08-03T20:45:50.554+1200 Footer {}
Logging output
The List CDRs tool writes its main output to the console, but it can be configured to write some extra debugging to a log file.
It uses the log4j logging library, and its log4j configuration file is located at ipsmgw-sdk/list-cdrs/log4j.properties
.
By default, it will log to ipsmgw-sdk/tools/list-cdrs/logs/list-cdrs.log
. It logs very little when using the default configuration — the log file will typically be empty unless configured for debug logging.
To enable debug logging, change the log level on the last line of the log4j.properties
file to DEBUG
:
log4j.logger.sentinel.cdr=DEBUG
Extension AVPs
Built-in AVPs and extension AVPs
The binary CDR format contains Diameter AVPs encoded in binary form, and the List CDRs tool decodes these binary AVPs before printing them in a human readable format.
The tool has built-in knowledge of AVPs which are defined in Diameter protocols such as Rf and Ro.
It can also be customized with knowledge of user defined extension AVPs, by providing definitions of those AVPs in YAML files.
The List CDRs tool looks in the list-cdrs/extension-avps
directory for YAML based files which define these extension AVPs.
A default installation of the List CDRs tool contains a DiameterExtension-AVP.yaml
file inside this directory, which defines OpenCloud’s extension AVPs. This means that by default, the List CDRs tool recognizes all the AVPs in the CDR files produced by Sentinel.
Known AVPs vs Undefined AVPs
When encountering an AVP which it does not recognize, the List CDRs tool treats it as an Undefined AVP. Because the tool can’t see which type of AVP it is (e.g. UTF8String
or Integer32
), it prints the raw binary content of the AVP in hexadecimal format.
This is how the List CDRs tool will print an extension AVP that it doesn’t recognize:
Undefined-AVP[code=1029,vendor=19808,hex=64 61 4a 76 69 5f 64 4e 69 65 5f 57 5f 76 2d 66 7a 44 4f 66 6c 67,ascii=daJvi_dNie_W_v-fzDOflg],
This is how the List CDRs tool prints that same extension AVP, when that AVP is configured as an extension AVP (see below):
OC-Call-Id[daJvi_dNie_W_v-fzDOflg],
Built-in extension AVPs
This is an excerpt from the default extension AVP configuration file at
list-cdrs/extension-avps/DiameterExtension-AVP.yaml
, showing the first two extension AVPs:
$ cat extension-avps/DiameterExtension-AVP.yaml !profiles DiameterExtension-AVP: id: name: 'Diameter Extension AVP' vendor: 'OpenCloud' version: '2.7' imports: null profiles: ? '' : AvpCode: 0 AvpName: null AvpType: null MandatoryRule: 1 ProtectedRule: 1 VendorId: 0 OC-Sentinel-Selection-Key: AvpCode: 1001 AvpName: OC-Sentinel-Selection-Key AvpType: UTF8String MandatoryRule: 1 ProtectedRule: 1 VendorId: 19808 OC-Play-Announcement-Id: AvpCode: 1002 AvpName: OC-Play-Announcement-Id AvpType: Integer32 MandatoryRule: 1 ProtectedRule: 1 VendorId: 19808 [...]
Customisation of extension AVPs
To configure your own custom AVP, add a new file with the same opening structure as extension-avps/DiameterExtension-AVP.yaml
, but with your own extensions.
Be sure to use your own Vendor ID, which we’ll assume to be 19404 below for the sake of example. |
An example configuration file:
$ cat extension-avps/ACME-DiameterExtension-AVP.yaml !profiles DiameterExtension-AVP: id: name: 'Diameter Extension AVP' vendor: 'OpenCloud' version: '2.7' imports: null profiles: ? '' : AvpCode: 0 AvpName: null AvpType: null MandatoryRule: 1 ProtectedRule: 1 VendorId: 0 ACME-My-First-Custom-Code: AvpCode: 1000 AvpName: ACME-My-First-Custom-Code AvpType: UTF8String MandatoryRule: 1 ProtectedRule: 1 VendorId: 19404 ACME-My-Second-Custom-Code: AvpCode: 1000 AvpName: ACME-My-Second-Custom-Code AvpType: UTF8String MandatoryRule: 1 ProtectedRule: 1 VendorId: 19404 [...]
After you have created such a file you will also have to add the AVP names to the Charging
profile in the DiameterExtensions
profile table, which lives in the file extension-avps/DiameterExtensions.yaml
. The profile consists of an array that lists all of the desired AVPs in the format <profile table name>/<profile name>
. So for the two AVPs from the example above you would have to add these two lines to the Charging
profile:
- DiameterExtension-AVP/ACME-My-First-Custom-Code - DiameterExtension-AVP/ACME-My-Second-Custom-Code
Note that the profile to use for the supported extension AVP list is configured with the ExtensionAvpSet
property of the Diameter RA. See Configuring Extension AVPs for the full documentation of these profile tables.
The required fields for each AVP:
- AvpCode
-
The code of the AVP. If using your own vendor code, then this AVP code is within your own namespace.
- AvpName
-
The name of the AVP.
- AvpType
-
The type of the AVP. See the available AVP types below.
- MandatoryRule
-
The "M" bit or Mandatory bit. Indicates whether support of the AVP is mandatory on the receiving end. Valid values are:
-
0 - MUST
-
1 - MAY
-
2 - MUSTNOT
-
- ProtectedRule
-
The "P" bit, indicating the need for encryption. Valid values are:
-
0 - MUST
-
1 - MAY
-
2 - MUSTNOT
-
- VendorId
-
The Vendor ID of the company which has defined this AVP.
- The available AVP types
-
-
OctetString
-
Integer32
-
Integer64
-
Unsigned32
-
Unsigned64
-
Float32
-
Float64
-
Grouped
-
Address
-
Time
-
UTF8String
-
DiameterIdentity
-
DiameterURI
-
Enumerated
-
IPFilterRule
-
QoSFilterRule
-
Undefined
-
Installing Protobuf
Protobuf 2.3.0 is required to build and extend CDR modules included with the SDK. The SDK infrastructure makes this version available for download from an Ant target.
Protobuf 2.3.0 can be downloaded as a standalone package here. To complete installation, follow the instructions in the included README.txt . |
Installing Protobuf from the SDK using Ant
To install Protobuf use the install-protobuf
Ant build target under the ipsmgw-sdk/tools
directory:
$ cd /home/testuser/ipsmgw-sdk/tools $ ant install-protobuf init-build-extensions: [...] init-tools-common: install-protobuf: [echo] [echo] Retrieving Protobuf... [mkdir] Created dir: /home/testuser/ipsmgw-sdk/tools/target [get] Getting: https://s3-ap-southeast-2.amazonaws.com/ocaws-downloads/third-party/google/protobuf/protobuf-2.3.0.tar.gz [get] To: /home/testuser/ipsmgw-sdk/tools/target/protobuf-2.3.0.tar.gz [get] .................................................... [get] .................................................... [get] .................................................... [get] .................................................... [get] ..... [echo] [echo] Protobuf retrieved. [echo] [echo] Unpacking Protobuf... [echo] [gunzip] Expanding: /home/testuser/ipsmgw-sdk/tools/target/protobuf-2.3.0.tar.gz to /home/testuser/ipsmgw-sdk/tools/target/protobuf-2.3.0.tar [untar] Expanding: /home/testuser/ipsmgw-sdk/tools/target/protobuf-2.3.0.tar into /home/testuser/ipsmgw-sdk/tools [echo] [echo] [echo] Protobuf unpacked. [echo] Requires further install steps, please read protobuf-2.3.0/README.txt for further details. [echo] BUILD SUCCESSFUL Total time: 6 seconds
See Setting up Ant in the Sentinel IP-SM-GW SDK guide. |
To complete installation, follow the instructions in ipsmgw-sdk/tools/protobuf-2.3.0/README.txt
.
Uninstalling Protobuf
If you want to uninstall the version of Protobuf installed by the SDK, use the uninstall-protobuf
Ant target under the ipsmgw-sdk/tools/
directory:
$ cd /home/testuser/ipsmgw-sdk/tools $ ant install-protobuf init-build-extensions: [...] init-tools-common: uninstall-protobuf: [echo] Uninstalling (deleting) the protobuf install from: /home/testuser/ipsmgw-sdk/tools/protobuf-2.3.0/ [delete] Deleting directory /home/testuser/ipsmgw-sdk/tools/protobuf-2.3.0 BUILD SUCCESSFUL Total time: 2 seconds
Alternatively, just delete the protobuf-2.3.0
directory:
$ rm -rf ipsmgw-sdk/tools/protobuf-2.3.0/
SIP Transports and Routing
This page describes how SIP requests are routed to and from the IPSMGW .
The ICSCFURI
and SipTransport
parameters in the Shared Configuration Profile determine how SIP requests are routed to and from the IPSMGW.
Outbound SIP requests
The ICSCFURI
parameter specifies the URI of the I-CSCF in the operator’s network. The IPSMGW inserts this URI in the Route
header of outbound requests. This determines the address, port and transport protocol that will be used when sending the request.
ICSCFURI
is parsed as a SIP URI as per section 19.1 of RFC 3621. It may use hostnames or IP addresses, and also the port and transport may be specified. Some valid examples are shown below:
-
sip:icscf.home1.net
-
sip:10.45.200.1:5062;lr;transport=tcp
-
sip:server5.ims.example.com:5060
The "lr" parameter is automatically added to the I-CSCF’s URI when it is used in an outgoing request’s Route header. It does not need to be specified in ICSCFURI . |
In an operator network it will usually be preferable to use a FQDN without port or transport parameters, such as sip:icscf.home1.net
. The IPSMGW will then use RFC 3263 DNS procedures to dynamically resolve the address, port and transport of the I-CSCF. This means the operator can easily change the I-CSCF location in the DNS, without needing to update clients. For testing purposes it may sometimes be useful to use explicit IP addresses, ports or transports.
Inbound SIP requests
The SipTransport
parameter is used when IPSMGW needs to construct its P-Asserted-Identity
address. The routing of inbound requests, such as delivery reports, is determined by this address.
The P-Asserted-Identity
address is constructed using the local IP address and port configured in the SIP-SIS resource adaptor, and the transport specified by SipTransport
. This may be "tcp" or "udp".
An SM-over-IP receiver that sends a delivery report to the IPSMGW obtains the address from the P-Asserted-Identity
header in the MESSAGE it received from the IPSMGW (3GPP TS 24.341 §5.3.2.4).
For example, when IPSMGW delivers a short message, it puts its own address in the P-Asserted-Identity
header.
MESSAGE tel:+4475500002222 SIP/2.0
From: <sip:ipsmgw-address:5060;transport=udp>;tag=096724a
To: <tel:+4475500002222>
P-Asserted-Identity: <sip:ipsmgw-address:5060;transport=udp>
Content-Type: application/vnd.3gpp.sms
...
When the SM-over-IP receiver sends its delivery report request, it uses this address in the Request-URI:
MESSAGE sip:ipsmgw-address:5060;transport=udp SIP/2.0
From: <tel:+4475500002222>;tag=5623989
To: <sip:ipsmgw-address:5060;transport=udp>
P-Asserted-Identity: <tel:+4475500002222>
Content-Type: application/vnd.3gpp.sms
...
In this way, delivery reports are routed to the IPSMGW using the configured SipTransport
.
Resource Adaptors
In Rhino, a resource adaptor (RA) provides the interface between the application (Sentinel IP-SM-GW) and the network. Sentinel IP-SM-GW makes use of a number of Resource Adaptors, for purposes ranging from database connections to network integration.
OpenCloud Resource Adaptors used by Sentinel IP-SM-GW
Sentinel IP-SM-GW uses the following Resource Adaptor Entities out of the box.
Resource Adaptor Entity | Purpose |
---|---|
cassandra-ipsmgw |
communication with the Cassandra Database for IPSMGW specific tables |
cassandra-ipsmgw-registrar |
communication with the Cassandra Database for IPSMGW Registration Ownership specific tables |
cassandra-third-party-reg |
communication with the Cassandra Database for Registrar specific tables |
cdr |
writing of call detail records (or 3GPP Charging Data Records) |
cginmapra |
sending/receiving MAP messages to/from any network element |
diameter-sentinel-internal |
internal Ro communication between protocol handling front-ends and the internal mediation subsystem |
diameterro-0 |
communication with Online Charging Systems |
ipsmgw-correlation-ra |
enabling the correlation of IPSMGW session data with subscriber data retrieved from the HLR |
sentinel-management |
management of Sentinel subsystems |
sh-cache-microservice-ra |
communication with the HSS |
sip-sis-ra |
SIP interface for the IP-SM-GW |
sipra |
utility mechanisms for the SIP protocol |
uid |
allocation of globally unique IDs |
Further information on specific Resource Adaptors
Below are overviews of:
Within Sentinel IP-SM-GW, the main users of the Sh Cache Microservice RA are:
-
PS Delivery feature --- uses the sh-cache-microservice-ra to subscribe to UE Reachability for IP Sh-Notifications
For more information on UE Reachability see UE Reachability for IP Notification Flows |
CDR Resource Adaptor
CDR resource adaptor entities
The Sentinel installer creates a CDR resource adaptor entity called cdr
. This resource adaptor entity is used by all Sentinel services.
CDR resource adaptor configuration
Refer to the CDR RA Documentation for more information about the CDR RA. |
The cdr
resource adaptor entity is configured to use the cdr-stream
profile of the CdrStreamConfiguration
profile table by default.
The output behaviour of the CDR resource adaptor can be customised by modifying this profile in accordance with the CDR RA Documentation.
Sentinel configuration requirements
The cdr
RA entity must be configured with CdrFileType=Binary
.
For more information about CDRs in the Sentinel platform, refer to:
-
Working with CDRs section of this administration guide to learn about the content of Sentinel CDRs.
-
Customising CDRs in the Extending Sentinel with the SDK guide to learn how to customise the format of the CDRs that Sentinel creates, as well as customising the data included in the CDRs.
Correlation Resource Adaptor
Correlation RA Overview
What is the Correlation RA?
The Correlation RA provides a mechanism to allocate a routing number with correlation data. The routing number and associated correlation data is replicated across the Rhino cluster. All nodes in the cluster have access to read/write correlation data.
This is used in the IP-SM-GW in order to allocate a correlation IMSI as part of the MT Delivery flows. The feature that performs this function is the Generate MT Correlation Id feature.
Below are procedures for [configuration], [monitoring].
Configuring a Correlation RA entity
A Correlation RA entity configuration consists of:
The Correlation Ra Configurer in the installer configures the GenerateMTCorrelationIdFeature which makes use of the CorrelationProvider. The generate mt correlation id feature in IPSMGW Configuration |
The Correlation resource adaptor supports live re-configuration, so the administrator may update the configuration properties of a Correlation resource adaptor entity that has already been created. |
Correlation RA configuration properties
The Correlation RA configuration properties are:
Name |
Type |
Description |
|
String |
The SLEE profile table with an RA configuration profile for this RA entity. |
|
String |
The SLEE profile in the ConfigProfileTable with configuration for this RA entity. |
|
String |
The SLEE profile table with correlation ID pool definitions for this Correlation RA entity. |
For example, the IPSMGW Correlation RA entity has the following configuration:
[Rhino@localhost (#9)] listraentityconfigproperties ipsmgw-correlation-ra Configuration properties for resource adaptor entity ipsmgw-correlation-ra: ConfigProfile (java.lang.String): IPSMGWCorrelationConfigProfile ConfigProfileTable (java.lang.String): CorrelationConfigTable CorrelationIdPoolTable (java.lang.String): IPSMGWCorrelationIdPools
Correlation RA entity configuration profile
The Correlation RA configuration profile has the following attributes:
Name |
Type |
Description |
|
Int |
The maximum time (measured in ms) the Correlation RA will spend trying to allocate a correlation ID. |
|
Int |
The maximum time (measured in ms) that an active correlation ID is considered to be still valid. |
|
Int |
How many threads the Correlation RA entity should use. |
For example, the IP-SM-GW Correlation RA entity has the following configuration:
[Rhino@localhost (#8)] listprofileattributes CorrelationConfigTable IPSMGWCorrelationConfigProfile CorrelationIDExpiryTimerPeriod=55000 NumberOfThreadPool=5 RequestTimeout=5000
If a change is made to the profile, the following command to activate the changes:rhino-console updateraentityconfigproperties ipsmgw-correlation-ra |
Once a Correlation ID has been allocated it is returned to the pool either when the application returns it, or after CorrelationIDExpiryTimerPeriod
milliseconds. Once returned to the pool a Correlation ID is available for subsequent allocation.
Correlation RA entity ID pools configuration
Each Correlation RA entity has one or more correlation ID pools.
-
a default ID pool (optional)
-
a set of named ID pools. Each named ID pool is identified by a set of prefixes for choosing/selecting the ID pool. From the Correlation RA standpoint, the prefixes can be any address string. The client to the RA provides an address that the RA uses via a longestPrefix match address list search to select the pool to use.
Each correlation ID pool is defined in a SLEE profile in an ID pools profile table. There is one correlation ID pools table per Correlation RA entity.
By default the installer sets up one pool for every home PLMN ID, with 1 million prefixes distributed evenly amongst them.
The correlation resource adaptor entity will raise an alarm if there are no correlation ID pools configured, or if there are configuration errors with the correlation ID pools. |
Field name | Expected value |
---|---|
AddressPrefixes |
The MCC and MNC. If deploying rhino as a cluster this should be one entry for each cluster. |
NodeIds |
The rhino cluster ids |
IsPreconfiguredCorrelationIdSetUsed |
false |
PreconfiguredCorrelationIdSet |
null |
MinCorrelationIDInCluster |
The first possible fake IMSI. The MCC and MNC (the first 5 or 6 digits) must be the same as defined in |
MaxCorrelationIDInCluster |
The last possible fake IMSI. The MCC and MNC (the first 5 or 6 digits) must be the same as defined in |
CorrelationIDNumberOfDigits |
The number of IMSI digits depending on the network. Maximum number is 15 |
CorrelationIDRangePerNode |
Number of the fake IMSIs per cluster node |
If a change is made to the profile, the following command to activate the changes:rhino-console updateraentityconfigproperties ipsmgw-correlation-ra |
Ensuring that Correlation IDs have the appropriate number of digits
The correlation RA will always return a value with the size specified in CorrelationIDNumberOfDigits
by padding zeros. The proper configuration is to have the number of digits in MinCorrelationIDInCluster
and MaxCorrelationIDInCluster
to be equal to CorrelationIDNumberOfDigits
. In the following example, the number of digits is 10, and both the min and max values have 10 digits.
-
AddressPrefixes = 64452
-
CorrelationIDNumberOfDigits = 10
-
MinCorrelationIDInCluster = 6445200000
-
MaxCorrelationIDInCluster = 6445299999
There are two possible configuration options for correlation ID pools.
A prescribed set of IDs for each node
Defines the prescribed correlation IDs for each node in the following way:
-
NodeIds[0]
—PreconfiguredCorrelationIdSet[0]
which is a ‘:’ separated string containing all the correlation IDs forNodeIds[0]
-
NodeIds[1]
—PreconfiguredCorrelationIdSet[1]
which is a ‘:’ separated string containing all the correlation IDs forNodeIds[1]
-
etc.
‘:’ is used as a separator and not to specify a range. For example, to specify IDs 123 , 124 , 125 and 126 use a value of 123:124:125:126 . |
A range of correlation IDs (min, max) for each node
Defines the range of values used in each node in conjunction with the NodeIds
attribute in the following way:
-
The node whose identifier is
NodeIds[i]
has a range of values ofCorrelationIDRangePerNode[i]
-
Each cluster has a range of CorrelationIDs defined by:
[MinCorrelationIDInCluster, MaxCorrelationIDInCluster]
These values are allocated to the different cluster nodes in the following way:
-
NodeIds[0]
—[MinCorrelationIDInCluster … MinCorrelationIDInCluster + CorrelationIDRangePerNode[0]]
-
NodeIds[1]
—[MinCorrelationIDInCluster + CorrelationIDRangePerNode[0] + 1 … MinCorrelationIDInCluster + +CorrelationIDRangePerNode[0] + 1 + CorrelationIDRangePerNode[1]]
-
etc.
The maximum number of correlation IDs defined in the range is 1,000,000.
Provisioning Interfaces
The Correlation RA configuration and ID pools are provisioned using the Sentinel REST API or web interface.
Monitoring Correlation RA entity statistics
Each Correlation RA entity collects the following statistics that may be monitored via the Rhino statistics client.
Counters
Name | Description |
---|---|
|
Count of correlation IDs which have been requested via findCorrelationEntry() |
|
Count of correlation queries which returned immediately (synchronous delivery) as the local RA had the data available. |
|
Count of correlation queries which did not return immediately (asynchronous delivery) as the local RA did not have the data available. |
|
Count of correlation queries which required delivering data to another correlation RA instance. |
|
Count of correlation queries which could not be remotely delivered as the destination RA for a correlation ID was unknown. |
In addition to the above statistics there are additional statistics use by Generate MT Correlation Id as the Generate MT Correlation Id feature uses the Correlation RA.
The count correlationGets should equal the sum of localGets + remoteGets . These statistics can use used to create threshold-based alarms. |
Diameter Resource Adaptor
Diameter resource adaptors
There are currently 2 Diameter Ro Resource Adaptor Entities in Sentinel IP-SM-GW:
-
diameterro-0
— for OCS connections -
diameter-sentinel-internal
— used as a message factory by mappers in Sentinel’s Diameter mediation layer.
diameterro-0
and diameter-sentinel-internal
are used by all Sentinel services.
Session timeouts
The default Sentinel configuration has a 10 minute timeout for diameterro-1
(client) and 13 minute timeout for diameterro-0
(OCS). This configuration ensures that if there are events dropped due to overload, the ActivityEndEvents fired on the RA entities will cause the client side to end first. The 3 minute gap is set to allow time for all the ActivityEndEvents on the client side to be delivered before any are fired on the OCS side due.
Diameter version configuration
The Diameter version spoken on the network to either the OCS or the Diameter client can be configured by setting two properties in the relevant resource adaptor. To change the version used in the OCS dialog, diameterro-0
should be reconfigured. Likewise, to change the version used on the client dialog (Sentinel Diameter
only), diameterro-1
should be reconfigured. The Diameter version used by diameter-sentinel-internal
should not be reconfigured, as it is tied to the internal implementation of Sentinel.
When reconfiguring the Diameter version of either of the external resource adaptors, two fields must be set - Slee3GPPVersion
and 3GPPVersion
. Slee3GPPVersion
should always be set to Vcb0
. This is the version of Diameter used by Sentinel internally. 3GPPVersion
can be set to the desired protocol version to be used over the network, ranging from V820
to Vcb0
.
Alternatively, the Diameter version spoken to the OCS can be set during installation.
OCS load balancing
Load balancing of OCS connections can be achieved using the diameterro-0
resource adaptor entity, by configuring multiple hosts within a realm and addressing messages to the realm only (not the host).
Example configuration for OCS load balancing
This example shows the diameterro-0
resource adaptor entity configured to load balance across two OCS nodes.
-
The resource adaptor entity config properties show that it is configured using a profile in the
DiameterConfig
table. -
The config profile shows that the known OCS nodes are named
diameterserver
anddiameterserver1
. -
The routing priority metric for both nodes is set to 1 to indicate equal priority, meaning that load balancing will be applied.
-
The
DiameterMediationOcsConfigurationTable
configuration profile at platform scope does not specify a host, so all outbound Diameter messages will not have the destination host set, but only the realm. This means the resource adaptor entity will round robin among all the hosts configured for the specified realm (in this caseopencloud
). However this behaviour can be overridden on a per-session basis by setting theOCSId
field in session state using, for example,SubscriberDataLookup
or a custom feature added with the SDK.
The following rhino-console
session shows the complete configuration:
[Rhino@localhost (#0)] listraentityconfigproperties diameterro-0 Configuration properties for resource adaptor entity diameterro-0: 3GPPVersion (java.lang.String): Vcb0 BaseMessageApplicationID (java.lang.Integer): 0 CertificateKeyStore (java.lang.String): CertificateKeyStorePassword (java.lang.String): CipherSuites (java.lang.String): ConfigurationProfile (java.lang.String): DiameterConfig/DiameterRoOcsProfile ConfigurationProfilePollTime (java.lang.Integer): 0 ConnectTimeout (java.lang.Long): 30000 ExtendedTransportConfiguration (java.lang.String): ExtensionAvpSet (java.lang.String): DiameterExtensions/Charging ExtensionAvpSetPollTime (java.lang.Integer): 0 ExtensionMessages (java.lang.Boolean): true FireToServiceID (java.lang.String): ForceReconnectAfterDPR (java.lang.Boolean): true IOClientWorkers (java.lang.Integer): 0 IOServerWorkers (java.lang.Integer): 0 Quirks (java.lang.String): ReconnectDelay (java.lang.Long): 5000 RequestTimeout (java.lang.Long): 2000 SSLSessionTimeout (java.lang.Integer): 0 ServiceContextId (java.lang.String): session@opencloud.com SessionTimeout (java.lang.Long): 780000 SupportedVendorIds (java.lang.String): ThreadPoolSize (java.lang.Integer): 0 TrustKeyStore (java.lang.String): TrustKeyStorePassword (java.lang.String): WatchdogTimeout (java.lang.Long): 30000 WorkQueueSize (java.lang.Integer): 0 slee-vendor:com.opencloud.rhino_max_activities (java.lang.Integer): 0 slee-vendor:com.opencloud.rhino_replicate_activities (java.lang.String): none [Rhino@localhost (#1)] listprofileattributes DiameterConfig DiameterRoOcsProfile Action=LOCAL AllowUnknownPeers=true ApplicationId=0 ApplicationVendorId=0 EnableMultiNodeConfig=false Host=diameterclient ListenAddress={null} NodeIDs={null} PeerAddress=127.0.0.1 PeerConnectAtStartup=true PeerHost=diameterserver PeerPort=3868 PeerTable=<?xml version="1.0" encoding="ISO-8859-1"?> <!DOCTYPE peer-table PUBLIC "-//Open Cloud Ltd.//DTD Diameter Peer Table Configuration 1.1.0//EN" "http://www.opencloud.com/dtd/diameter-peer-table-1.1.0.dtd"> <peer-table allowUnknownPeers="true"> <!-- If allowUnknownPeers is true, then any peer may connect to this node. If allowUnknownPeers is not true, peers connecting to this node as clients must be defined in the Peer Table.--> <peer connectAtStartup="true"> <hostname>diameterserver</hostname> <!-- Will accept connections from this peer --> <port>3868</port> <address>127.0.0.1</address> <tls>false</tls> <option> <option-name>TCP_NODELAY</option-name> <option-type>java.lang.Boolean</option-type> <option-value>true</option-value> </option> </peer> <peer connectAtStartup="true"> <hostname>diameterserver1</hostname> <!-- Will accept connections from this peer --> <port>3868</port> <address>192.168.2.100</address> <tls>false</tls> <option> <option-name>TCP_NODELAY</option-name> <option-type>java.lang.Boolean</option-type> <option-value>true</option-value> </option> </peer> </peer-table> PeerUri={null} PerNodeHosts={null} PerNodeListenAddresses={null} PerNodePorts={null} PerNodeSecondaryAddresses={null} Port=3869 Product=OpenCloud Diameter ProductVendorId=19808 Realm=opencloud RealmTable=<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE realm-table PUBLIC "-//Open Cloud Ltd.//DTD Diameter Realm Table Configuration 1.1//EN" "http://www.opencloud.com/dtd/diameter-realm-table-1.1.dtd"> <realm-table> <realm> <realm-name>opencloud</realm-name> <application-route> <application> <application-id>4</application-id> <!-- 4=CCA --> <vendor-id>0</vendor-id> <!-- optional, default is zero --> </application> <action>LOCAL</action> <peer-ref> <hostname>diameterserver</hostname> <metric>1</metric> </peer-ref> <peer-ref> <hostname>diameterserver1</hostname> <metric>1</metric> </peer-ref> </application-route> </realm> <default-route> <peer-ref> <hostname>diameterserver</hostname> <metric>1</metric> </peer-ref> <peer-ref> <hostname>diameterserver1</hostname> <metric>1</metric> </peer-ref> </default-route> </realm-table> SecondaryAddresses={null} Transports=tcp UseTLS=false ValidDN={null} Version=1 [Rhino@localhost (#2)] listprofileattributes DiameterMediationOcsConfigurationTable UNSET:::: DestinationHost={null} DestinationRealm=opencloud TimeoutDuration=2000
SIP SIS Resource Adaptor
SIP SIS resource adaptor entity (sip-sis-ra)
Refer to the Service Interaction SLEE (SIS) documentation for more information about the SIP SIS resource adaptor. |
The sip-sis-ra
is used for initiating and third-party SIP dialogs for both the Sentinel SIP Service and the Sentinel Subscription Service.
Link name | Default Bound RA entity |
---|---|
|
|
Sentinel and SIS
The sip-sis-ra
interacts directly with the SIS, which is configured with compositions for the Sentinel SIP Service. The Sentinel SIP Service is triggered by all events from the SIP SIS RA entity. This behaviour is configurable. See the Service Interaction SLEE (SIS) documentation for more information about compositions and triggers.
Configuring SIS
Use the sis-console
or SIS REM Module to modify the default SIS and sip-sis-ra configuration properties; see the SIS Administration Guide and SIS REM Module User Guide for more details on managing the SIS instance.
Cassandra Storage
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, generating Message References, and tracking Registration Ownership. 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.
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.
Registration Ownership TTL
For Registration Ownership the TTL is defined as the largest expiry from Third Party Registration plus a configured time. The configured time value is defined in IPSMGWRegistrationTrackingCassandraConfigProfileTable. 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).
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 IF NOT EXISTS opencloud_thirdparty_reg WITH REPLICATION={'class' : 'SimpleStrategy' ,'replication_factor' : 3 };
-
For testing purposes, 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
IP-SM-GW Routing Information and Registration Ownership
-
The keyspace for routing information must be named
opencloud_ipsmgw_routing_info
-
The keyspace for registration ownership must be named
opencloud_ipsmgw_registration_ownership
-
For a production environment, the keyspace can be created such that it is replicated. A sample set of CQL commands for creating these keyspaces is:
CREATE KEYSPACE opencloud_ipsmgw_routing_info WITH REPLICATION={'class' : 'NetworkTopologyStrategy' ,'replication_factor' : 3 };
CREATE KEYSPACE opencloud_ipsmgw_registration_ownership WITH REPLICATION={'class' : 'NetworkTopologyStrategy' ,'replication_factor' : 3 };
-
For testing purposes, replication may not be necessary. A sample set of CQL commands for creating these keyspaces is:
CREATE KEYSPACE opencloud_ipsmgw_routing_info WITH REPLICATION={'class' : 'SimpleStrategy' ,'replication_factor' : 1 };
CREATE KEYSPACE opencloud_ipsmgw_registration_ownership WITH REPLICATION={'class' : 'SimpleStrategy' ,'replication_factor' : 1 };
Once the keyspaces are 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
uuid uuid, //The UUID generated for SAS correlation
primary key(mtcorrelationid)
)
WITH gc_grace_seconds = 14400; // 4 hours
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 = 14400; // 4 hours
USE opencloud_ipsmgw_registration_ownership;
CREATE TABLE IPSMGWRegistrationOwnership(
msisdn text, //MSISDN of the subscriber
ipsmgwsitegt text, //GT of the IPSMGW site that handled the registration for the subscriber
writetime timestamp, //The time that this record was written
primary key(msisdn,ipsmgwsitegt)
)
WITH gc_grace_seconds = 172800; // 2 days
The schemas are used by these features:
Initial Filter Criteria
Initial Filter Criteria (iFC) is the mechanism used by the IMS to invoke Application Servers. It applies to SIP initial requests.
Requirements for Sentinel IP-SM-GW
The Sentinel IP-SM-GW receives Third Party Registration and SIP MESSAGE requests. In particular the SIP MESSAGE requests contain SMS RP-DATA
level information encapsulated in the body of the SIP MESSAGE request.
The IP-SM-GW receives SIP MESSAGE requests where the addressing requirements for those SIP MESSAGE requests are standardised in 3GPP TS 24.341. The addressing for these messages provides the requirements for the iFC configuration.
These are:
-
Submitting a short message - the Request-URI uses the Public Service Identity of the Service Centre of the SM-over-IP sender.
-
Sending a notification about SM-over-IP receiver having memory available - the Request URI which shall contain the IP-SM-GW address, if available, and shall contain PSI of the SC otherwise.
-
Sending a delivery report - the Request-URI is set to the received P-Asserted-Identity in the received SIP MESSAGE request including the delivered short message.
This means that there is:
-
One PSI for each Service Centre - that can include an AS name that resolves (via DNS) to any IP-SM-GW cluster node that represents the Service Centre.
-
One PSI for each cluster node - such that delivery reports can route directly to the appropriate node.
Flows for submitting a short message are shown in MO Submission Flows. The delivery report is part of the MT Delivery Flows and is mentioned as the SIP MESSAGE request containing an RP-ACK
.
Registration
The IP-SM-GW requires Third Party Registration details for various functions, so registrations need to be routed to the IP-SM-GW. First-Party register and response should be included in the Register messages. Depending on your HSS, the configuration for including first-party request and response messages could be on the iFC or the associated AS. The ServerName
name in the iFC should resolve to multiple AS nodes through DNS.
<?xml version="1.0"?>
<!-- Example IFC for sending registration messages to the IPSMGW -->
<InitialFilterCriteria>
<Priority>1</Priority>
<TriggerPoint>
<!-- ConditionTypeCNF 1 means logical OR of SPT elements in the same group then AND the SPT elements in different groups -->
<ConditionTypeCNF>1</ConditionTypeCNF>
<!-- logically, this TriggerPoint matches if the request is an Initial Registration or a Re-Registration or a De-registration -->
<SPT>
<Group>0</Group>
<Method>REGISTER</Method>
<Extension>
<RegistrationType>0</RegistrationType> <!-- INITIAL_REGISTRATION -->
</Extension>
</SPT>
<SPT>
<Group>0</Group>
<Method>REGISTER</Method>
<Extension>
<RegistrationType>1</RegistrationType> <!-- RE_REGISTRATION -->
</Extension>
</SPT>
<SPT>
<Group>0</Group>
<Method>REGISTER</Method>
<Extension>
<RegistrationType>2</RegistrationType> <!-- DE_REGISTRATION -->
</Extension>
</SPT>
</TriggerPoint>
<ApplicationServer>
<!-- The DNS name should resolve to a number of IP-SM-GW cluster nodes -->
<ServerName>sip:ipsmgw-cluster.example.com;transport=tcp</ServerName>
<DefaultHandling>0</DefaultHandling>
<Extension>
<IncludeRegisterRequest/>
<IncludeRegisterResponse/>
</Extension>
</ApplicationServer>
</InitialFilterCriteria>
Messages
Message Request containing Service Centre PSI
SIP MESSAGE requests that contain the Service Centre PSI should be routed to the IP-SM-GW if the Content-Type Header is equal to application/vnd.3gpp.sms
. This caters for SMS submission and notification about the SM-over-IP receiver having memory available (if it used the PSI of the SC).
<?xml version="1.0"?>
<!-- example IFC showing MESSAGE requests to the Service Centre PSI -->
<InitialFilterCriteria>
<Priority>2</Priority>
<TriggerPoint>
<!-- logically, this TriggerPoint matches if the request is a SIP MESSAGE AND the Content-Type is 'application/vnd.3gpp.sms' AND the host part of the Request-URI matches -->
<ConditionTypeCNF>1</ConditionTypeCNF>
<SPT>
<Group>0</Group>
<Method>MESSAGE</Method>
</SPT>
<SPT>
<Group>1</Group>
<SIPHeader>
<Header>Content-Type</Header>
<Content>application/vnd.3gpp.sms</Content>
</SIPHeader>
</SPT>
<SPT>
<Group>2</Group>
<RequestURI>service-centre.example.com</RequestURI>
</SPT>
</TriggerPoint>
<ApplicationServer>
<!-- The DNS name should resolve to a number of IP-SM-GW cluster nodes -->
<ServerName>sip:ipsmgw-cluster.example.com;transport=tcp</ServerName>
<DefaultHandling>0</DefaultHandling>
</ApplicationServer>
</InitialFilterCriteria>
The default SIP transport mechanism for AS communication is UDP. TCP can be specified by appending ;transport=tcp to the IP-SM-GW AS URI configured in the <ServerName> attribute. |
The ServerName name used is intended to be resolved to a number of IP-SM-GW node addresses through DNS. |
Message Request containing a per-node PSI
SIP MESSAGE requests that contain a per-node PSI should be routed to the specific IP-SM-GW node that is holding an Open TCAP Transaction from the SMS-C. These messages have the Content-Type
header equal to application/vnd.3gpp.sms
. This caters for the sending of a delivery report or a memory available notification (if it used the IP-SM-GW address).
There should be one iFC for each IP-SM-GW cluster node, containing its AS name. This name should resolve to only one AS node.
In 24.341 the specification text does not describe the SIP Message carrying a delivery report or a memory available report as being originating, therefore it is treated as terminating.
This iFC indicates that SIP MESSAGE Requests for the per-node PSI shall only be triggered to the IP-SM-GW in a terminating request. As the SIP MESSAGE request carrying a delivery report has an In-Reply-To
header containing a SIP Call-ID related to an earlier SIP MESSAGE transaction, the MESSAGE request containing the delivery report should not traverse other SIP-AS B2BUA’s (as B2BUA’s typically change the Call-ID as a message traverses the IMS).
<?xml version="1.0"?>
<!-- example IFC showing MESSAGE requests to a per node PSI -->
<InitialFilterCriteria>
<Priority>2</Priority>
<TriggerPoint>
<!-- logically, this TriggerPoint matches if the request is a SIP MESSAGE AND the Content-Type is 'application/vnd.3gpp.sms' AND the host part of the Request-URI matches AND (TERMINATING_REGISTERED OR TERMINATING_UNREGISTERED) -->
<ConditionTypeCNF>1</ConditionTypeCNF>
<SPT>
<Group>0</Group>
<Method>MESSAGE</Method>
</SPT>
<SPT>
<Group>1</Group>
<SIPHeader>
<Header>Content-Type</Header>
<Content>application/vnd.3gpp.sms</Content>
</SIPHeader>
</SPT>
<SPT>
<Group>2</Group>
<RequestURI>ipsmgw-node1.example.com</RequestURI>
</SPT>
<SPT> <!-- GROUP 3 elements are OR'd together -->
<Group>3</Group>
<SessionCase>TERMINATING_REGISTERED</SessionCase>
</SPT>
<SPT>
<Group>3</Group>
<SessionCase>TERMINATING_UNREGISTERED</SessionCase>
</SPT>
</TriggerPoint>
<ApplicationServer>
<!-- The DNS name should resolve to a single IP-SM-GW node -->
<ServerName>sip:ipsmgw-node1.example.com:5060;transport=tcp</ServerName>
<DefaultHandling>0</DefaultHandling>
</ApplicationServer>
</InitialFilterCriteria>
INVITE Request containing USSD content
The IP-SM-GW product implements support for USSD over IMS (USSI) interworking with MAP based USSD. This requires INVITE requests containing USSD messages to be routed to the IP-SM-GW.
For originating USSI INVITEs an originating iFC needs to match the USSI INVITE. The following example matches all INVITEs with a Recv-Info header equal to g.3gpp.ussd
.
<?xml version="1.0"?>
<!-- example IFC showing USSI INVITEs routing to the IP-SM-GW -->
<InitialFilterCriteria>
<Priority>2</Priority>
<TriggerPoint>
<!-- logically, this TriggerPoint matches if the request is a SIP INVITE AND the Recv-Info header matches the value g.3gpp.ussd -->
<ConditionTypeCNF>1</ConditionTypeCNF>
<SPT>
<ConditionNegated>0</ConditionNegated>
<Group>0</Group>
<Method>INVITE</Method>
<Extension/>
</SPT>
<SPT>
<ConditionNegated>0</ConditionNegated>
<Group>1</Group>
<SIPHeader>
<Header>Recv-Info</Header>
<Content>g.3gpp.ussd</Content>
</SIPHeader>
<Extension/>
</SPT>
</TriggerPoint>
<ApplicationServer>
<!-- The DNS name should resolve to a number of IP-SM-GW cluster nodes -->
<ServerName>sip:ipsmgw-cluster.example.com;transport=tcp</ServerName>
<DefaultHandling>0</DefaultHandling>
</ApplicationServer>
</InitialFilterCriteria>
An alternative to the approach used here is to define a wildcard Public Service Identity for USSD over IMS.
The Sentinel VoLTE product typically receives INVITE requests. The iFC used to trigger Sentinel VoLTE should exclude INVITEs matching USSD over IMS requests. |
License Requirements
This page gives information about license requirements for running Sentinel IP-SM-GW.
Required License Functions
All services and resource adaptors require the following license function:
License Function | Optional | Required For |
---|---|---|
Rhino |
No |
Capacity |
This following sections list the additional license functions required by certain components of Sentinel IP-SM-GW. Some of the components listed below modify the Rhino license function to be only necessary for Activation
instead of Capacity
.
Not all of the components listed below will be present in all Sentinel IP-SM-GW deployments. |
Services
Resource Adaptors
SIS-SIP/EasySIP RA
Component Name: SIS-SIP/EasySIP RA
License Function | Optional | Required For |
---|---|---|
Rhino-SIS |
No |
Capacity |
Rhino-SIS-SIP |
No |
Capacity |
Rhino-SIS-SIP-External-Service |
Yes |
Capacity |
Rhino-SIS-SIP-Local-Service |
Yes |
Capacity |