How to do specific things with SigScale OCS.

Add a subscriber

To add a subscriber you must choose a Product Offering to subscribe to, create a Service instance and add an account balance. The web components front end provides a dialog to accomplish all of these steps in the Subscribers → Services view. Select the green icon to open the dialog:

Open

In the Product tab select a Product Offer from the drop down menu. In the Authentication tab enter the Service identifier (e.g. MSISDN). In the Credit tab add an amount to the account balance. Select Submit after completing all tabs.

Balance Top-Up with API

Use the TM Forum Prepay Balance API (TMF654) to create a new balance Bucket or apply credit toward the total balance. Below is example of adding $10 through a balance adjustment using the curl command line utility:

View available balance

The web components front end provides the total amounts of each bucket type in the Subscribers → Products view:

Open

Add an DIAMETER client (DRA/SGSN/PGW)

The IP address of each directly connected DIAMETER/RADIUS client must be included in the Clients view (default behaviour is to ignore requests from unknown clients). In the Clients view select the green icon to open the dialog:

Note: The Client address must match a value of the Host-IP-Address AVP in a Capabilities-Exchange-Request (CER) from the peer.

Add a REST API user

Access to the REST APIs, including the progressive web app front end, requires authorized users to be added in the Users view. Select the green icon to open the dialog:

Add an Offering in the Product Catalog

A new product Offer, which may be subscribed to by customers, may be created in the Catalog → Offering view. Select the green icon to open the dialog:

In the Offering tab give it a name and optionally a description. You must select a Product Specification (i.e. Prepaid Data) from the dropdown list. Continue on the Prices tab by adding Price(s) to apply to usage of the Offer. Select Submit after adding all Prices and optionally Alterations.

Configure DIAMETER/RADIUS services

By default DIAMETER and RADIUS services are listening on all interfaces (0.0.0.0). The DIAMETER “acct” applications (Ro/Gy/Gx) are on port 3868 and “auth” applications (EAP,NAS,STa,SWm,SWx,S6a,S6b) on port 3869. RADIUS auth is on port 1812 and acct on port 1813.

The protocol services may be configured in the system configuration file/home/otp/releases/<VERSION>/sys.config. There is a clause for each protocol with a list of the configured services. The following example has RADIUS disabled and only one DIAMETER acct service listening on 10.10.0.1 port 3868 with two options set:

Identify Subscribers by IMSI

The DIAMETER “acct” service option sub_id_type is used to configure how the Subscription-Id AVP is matched to Service table entries. The value is a list of types in priority order (default [msisdn]). If you just want to match on IMSI add the option {sub_id_type, [imsi]} to the diameter configuration (as above).

Monitor with an SNMP Manager

SigScale OCS supports fault & performance management (FM & PM) with the Simple Network Management Protocol (SNMP). A management information base (MIB) for the OCS application is provided as well as IETF standard MIBs and SigScale's versions of IETF draft MIBs. The MIBs may be found in ~/lib/ocs-*/mibs.

Get the description of the SNMP agent:
snmpget -v2c -c public localhost:4161 SNMPv2-MIB::sysDescr.0
SNMPv2-MIB::sysDescr.0 = STRING: Online Charging System (OCS)

Get the DIAMETER peer statistics (peer must be up):
snmpwalk -v2c -c public -M +lib/ocs-*/mibs:lib/sigscale_mibs-*/mibs localhost:4161 SIGSCALE-DIAMETER-CC-APPLICATION-MIB::dccaPerPeerStatsTable
_{[substitute version numbers for * in above example]}

Monitor with Prometheus

A Prometheus exporter providing DIAMETER statistics is available with:

GET /metrics

Health Check

Overall system health is reported using the IETF Health Check format:

GET /health

Initialize a Cluster

Multiple instances of the software may form a distributed system where each node has transactional access to the same tables. A cluster provides resiliency as each node is equally available to service requests on it’s provisioned interfaces (DIAMETER, REST, etc.).

The procedure given here is for initializing a new cluster, we begin by stopping and deleting all existing tables. Then start each node manually, connect the cluster, initialize new distributed tables and restart:
user@hostA:~$ sudo systemctl stop ocs; sudo -iu otp
otp@hostA:~$ rm db/*
otp@hostA:~$ ERL_LIBS=lib erl -sname ocs -config releases/<VERSION>/sys
user@hostB:~$ sudo systemctl stop ocs; sudo -iu otp
otp@hostB:~$ rm db/*
otp@hostB:~$ scp hostA:..erlang.cookie .
otp@hostB:~$ ERL_LIBS=lib erl -sname ocs -config releases/<VERSION>/sys
(ocs@hostA)1> net_kernel:connect_node(ocs@hostB).
(ocs@hostA)1> ocs_app:install().
(ocs@hostA)1> q().
(ocs@hostB)1> q().
otp@hostA:~$ exit
user@hostA:~$ sudo systemctl start ocs
otp@hostB:~$ exit
user@hostB:~$ sudo systemctl start ocs
_{[substitute current version number for <VERSION> above]}

Expand a Cluster

The procedure below shows adding a new node (ocs@hostC) to a cluster by copying the tables from an existing node (ocs@hostB).

user@hostC:~$ sudo systemctl stop ocs; sudo -iu otp
otp@hostC:~$ rm db/*
otp@hostC:~$ ERL_LIBS=lib erl -sname ocs -config releases/<VERSION>/sys
(ocs@hostC) 1> ocs_app:join('ocs@hostB').
(ocs@hostC) 2> q().
otp@hostC:~$ exit
user@hostC:~$ sudo systemctl start ocs
_{[substitute current version number for <VERSION> above]}

Subscribe to Notifications

Notification of events is supported using the pattern described in TMF630. Each API has a /hub resource collection of subscriptions to API events. An example of subscribing to TMF635 Usage Management events:

curl -u admin:admin -H "Content-Type: application/json" -d '{"callback": "http://bss.example.net/listener"}' http://ocs.example.net:8080/usageManagement/v1/hub

Each event on the API will cause an HTTP POST to the provided callback URL. Note that no retries are performed and that any error will result in the subscription being removed.

Low Balance Notification

Subscribe to TMF654 Prepay Balance API notifications with a query on accumulated balance for notification of low balance. The following example subscribes to notification on events where the total data balance is less than 500MB:

curl -u admin:admin -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{"callback": "http://bss.example.net/listener", "query": "totalBalance.units=octets&totalBalance.amount.lt=500000000"}' http://ocs.example.net:8080/balanceManagement/v1/hub

A system threshold must be set to enable accumulated balance events internally. The application environment variables threshold_bytes, threshold_cents, threshold_seconds and threshold_messages may be configured in the sys.config file.

Add Tariff Tables

Tariff Tables may be managed in the Catalog → Tariff Table view or TMF639 API however this relies on pre-existing prefix tables of the same name implemented in mnesia. Creating mnesia tables is left as a DevOps role procedure out of concern for system stability. The following is an example of creating a persistent prefix table named international distributed on all nodes of the cluster:

(ocs@host)1> ocs_gtt:new(international, [{disc_copies, [node() | nodes()]}]).

REST Pagination

Using the HTTP GET method on a REST Collection may result in a huge response. To prevent resource exhaustion, on the client or server, pagination is used. By default a maximum of 1000 items will be provided in a single response. The Content-Range header shall indicate the range of the response and the total size (if available):

Etag: 1643855624410-7330
Accept-Ranges: items
Content-Range: items 1-1000/3768

The Etag header provides a tag which may be used to continue (default timeout 1m) a series of paginated GET requests by providing it in an If-Match header and specifying the next page with the Range header:

If-Match: 1643855624410-7330
Range: items=1001-2000

Set rest_page_size and rest_page_timeout in sys.config.

Export IPDR Logs

SigScale OCS creates detail record (IPDR) archives from the accounting log, on a scheduled basis (default nightly). These binary log files, named with creation date and time, are stored in /home/otp/log/ipdr/. These logs may be exported in a CSV format as shown in the following examples:

sudo -iu otp env ERL_LIBS=lib bin/export_ipdr wlan 2022-01-13T12:19:24.011Z csv
sudo -iu otp env ERL_LIBS=lib bin/export_ipdr voip 2022-01-13T12:19:24.011Z csv

Exported files can be found in /home/otp/log/export

Increase Log Retention

The number of events available to be queried is dependent on the number of log files and their size. Internally events are stored as binary objects in a FIFO wrap log with a fixed maximum size. The default configuration may be overridden in the system configuration file /home/otp/releases/<VERSION>/sys.config. For example configure the acct log with one hundred files, of 10MB each, as below.

There are three logs: acct (OCS), auth (AAA) and abmf (Account Balance Management Function).

Home Subscriber Server (HSS)

The 3GPP AAA Server function will use AKA credentials (K, OPc) in the Service table or, absent that, request authentication vectors from an HSS with DIAMETER SWx. Configure a DIAMETER Client as described above. The Destination-Realm for the HSS is configured using the ocs application environment variable hss_realm, and optionally hss_host.

Administratively Disable Service

You may temporarily disable a Service to prevent it from being authorized afterwards, and to disconnect any sessions currently progress. In the Service view dialogs, on the Authorization tab, there is a toggle labled Enable.

An example using curl:

Emulate a DIAMETER Client

You may simulate a DIAMETER client establishing a peering and sending Credit Control Requests (CCR) with the command line utilities provided in /home/otp/bin for PS, IMS and SMS service usage. The otp user's shell environment is setup to support these utilities. Use the --help argument to get details on usage. Optional arguments are denoted with square brackets with the given value being the default if that option is omitted.

user@host:~$ sudo -iu otp
otp@host:~$ data_session --help
usage: data_session [--msisdn 14165551234] [--imsi 001001123456789] [--interval 1000] [--updates 1] [--ip 127.0.0.1] [--raddr 127.0.0.1] [--rport 3868]