Overview

ocs

Copyright © 2016 - 2026 SigScale Global Inc.

Version: 3.4.54

This application implements an Online Charging System (OCS).

Table of Contents

• Introduction
  
• Features
  
• Schema
  
• Product Specifications
  
• Installation
  
• Operation
  
• Configuration
  

Introduction

This application implements functions used by communications service providers (CSP) for authorization and charging of prepaid services. It is built to TM Forum standards with Open APIs for management of product, service and balance. A web components front end is also provided as a progressive web app (PWA) for standalone use.

Features

SigScale OCS provides the following high level functions.

Product Catalog

An internal catalog of Product Offerings and Prices is provided which may be synched from an external master catalog (TMF620) where available. Any number of offers may be created, with simple or complex rating, using multiple Prices matched to appropriate service usage. Tariff tables may be used to rate by origination and/or destination address prefix as well as visited network (VPLMN MCC-MNC). Product Offerings may be bundled to create Voice, Data and Messaging offers.

Product Inventory

An internal inventory of subscribed Products is maintained which may be synched from an external master inventory (TMF637) where available. Account Balance Buckets are associated with a Product instance (subscription) and may be shared by associated Services (devices).

Service Inventory

An internal Service Inventory contains the subscriber identifiers used to match reported service usage with a Product. It may be synched with an external master inventory (TMF638).

AAA

Authentication, authorization and accounting (AAA) functions are the foundation to commercial operations of a CSP. In a 3GPP OCS use case authentication will have already been ccomplished before a DIAMETER Ro/Gy Credit Control Request (CCR) is received by the OCS. Authorization is performed by the OCS based on the application of prevailing ratees and available account balance. Accounting is perormed by reserving and charging against account balance, in real time, during service usage.

Authentication is optionally provided. Subscriber credentials (i.e. password or K/OPc) may be stored internally with authentication performed over DIAMETER/RADIUS using EAP methods (AKA/AKA', PWD, TTLS).

OCS/CCS

An Online Charging System (OCS) performs real-time charging for services. A Converged Charging System (CCS) combines online (prepaid) and offline (postpaid) charging in one 5G Core function. An OCS/CCS authorizes subscribers' sessions subject to available credit on account and decrements account balance as services are consumed. When a subscriber's account balance is depleted authorization may be withdrawn and ongoing session(s) terminated.

Business Support Systems (BSS)

The OCS/CCS includes control plane interfaces to core networks but also integrates with Business Support Systems (BSS) which manage commercial operations and customer management. SigScale OCS is designed and built to make this integration as frictionless as possible. The diagram below represents a possible solution architecture.

Functional Distribution

A 3GPP OCS/CCS may be decomposed into OCF/CHF, RF and ABMF (3GPP TS 32.296). A protocol for the Re interface, based on DIAMETER, was partially specified however SigScale has progressed this work by aligning with the 5GC SBI for Nch and created the Nrf REST API described below.

OCF/CHF

The network facing protocols (DIAMETER, RADIUS) are handled by an Online Charging Function (OCF). In 5G Core this is the CHF.

RF

The Rating Function (RF) provided in SigScale OCS is driven entirely by the Product Offering Prices (POP) in the catalog. The RF determines which of the POPs apply and determines a tariff rate to apply for the requested service usage. In class B operation the RF and ABMF are colocated and the response is for the combined operation. In class A operation only the tariff rate to be applied is retruned and the OCF/CHF shall interact with the ABMF directly. The class of operation may be decided by the RF dynamically, a mix of class A and B may be used.

ABMF

The Account Balance Management Function (ABMF) supports reservation, debit and refund in monetary, byte, time and event units across multiple discrete Buckets. Each Bucket has it's own lifecycle period wth charging done across Buckets with a first to expire priority. External systems may use the TMF654 API to check accumulated balance, recgharge, etc..

PCRF

The Policy and Charging Rules Function (PCRF) is included which produces a DIAMETER Gx application service on the same ports as the Ro application (default 3868). Both static and dynamic Policy Rules installation on the Policy Enformenet Control Function (PCEF) is supported. Any number of Policy Tables may be created, containing any number of Policy Rules. A Product Offering may have a Policy Table associated with it, allowing QoS to be defined at the Product Offering level and automatically applied to subscribers. Rules may be managed with the PWA (GUI) or TMF639 API.

CAMEL

Support for 3GPP CAMEL (Customized Applications for Mobile network Enhanced Logic) protocol is available through an integration with SigScale CSE which provides a CAMEL Service Envirionment (CSE). The interface between CSE and OCS is the Nrf API described in the REST section below.

3GPP

This application conforms to 3GPP specifications for the interfaces, protocols and procedures of the OCS, PCRF and 3GPP AAA Server functions in the reference architecture. Supported interfaces include DIAMETER Ro/Gy, RADIUS and Nrf for OCS, Gx for PCRF and SWm/STa/SWx/S6b for AAA Server.

3GPP AAA Server

Non-3GPP access use cases are supported with the 3GPP AAA Server function which builds on the base AAA function and includes the 3GPP reference architecture interfaces SWm, STa, S6b and SWx. The SIM's AKA credentials (K, OPc) may be stored internally, for testing or standalone deployments. In normal operation the DIAMETER SWx application is used to retrieve authentication vectors from a Home Subscriber Server (HSS).

Trusted WLAN

Untrusted WLAN

Wi-Fi Direct

Schema

The table schema is a faithful mapping of TM Forum's Information Model SID. The product table represents Product Inventory. A row in this table represents a subscription and is associated to zero or one row of the offer table which represents the Product Offering collection. A row in the offer table may be associated with zero or more Pricing Logic Algorithms (PLA) implemented with prefix matching tables. A product table row may be associated with zero or more Balance Buckets as represented by the bucket table. The Service Inventory is represented by the service table. A product table row may be associated with zero or many service table rows while a service table row may be associated with at most one product table row.

Product Specifications

Rating and charging is controled by Characteristic values chosen when creating Product Offerings and Product Offering Prices. The Characteristics are defined in Product Specifications available with the Product Catalog API (TMF620) (/productCatalogManagement/v2/productSpecification/). The diagram below depicts the dependency relationships. An atomic Product Offering will include one of the Prepaid Product Specifications.

Installation

Before starting the application for the first time, mnesia should be initialized. Create a schema and start mnesia on all nodes where the application ocs application will run.

The following command will initialize ocs on the current node and create a default REST user "admin" with password "admin".

	(ocs-vances@rt)1> ocs_app:install().
	{ok,[httpd_group,httpd_user,bucket,offer,pla,product,service,client]}

	1> ocs:add_user("john", "g2k7hyeh6qa", "en").
	{ok,{1501829429047,149}}
	2> ocs:add_user("bss", "nfc9xgp32xha", "en").
	{ok,{1501829458220,157}}

The web UI also allows you to create users, making the above step unecessary.

Operation

The OCS application will start RADIUS & DIAMETER servers for authentication and accounting on the configured ports. The inets application may be started to provide a REST API and web user interface (UI).

DIAMETER

One or more diameter services are configured to enable peering with DIAMETER clients or Routing Agents (DRA).

OCS

A typical prepaid charging message sequence across the Ro or Gy interface is depicted below:

PCRF

A typical policy and charging control (PCC) message sequence across the Gx interface is depicted below:

AAA

A typical non-3GPP access message sequence across the SWm and SWx interfaces is depicted below:

Logging

Every detail of each DIAMETER/RADIUS transaction is logged to disk.

Disk Logs

Event details are logged to fixed size FIFO logs consisting of a configurable number, and size, of internally formatted files. Events are written to archive log files on a scheduled basis (default daily). These internally formatted archive logs may be exported on demand to a supported file format (e.g. CSV). A shell script is provided (bin/export_ipdr) for this purpose.

See acct_log_dir, acct_log_files, acct_log_rotate, acct_log_rotate_time, acct_log_size, auth_log_dir, auth_log_files, auth_log_size, ipdr_log_dir, and export_dir in the Configuration section below.

Elasstic Stack

Optionally DIAMETER/RADIUS transactions may be shipped to LogStash with the http input plugin.

See elastic_shipper in the Configuration section below.

REST API

The ocs application provides RESTful APIs built on the HTTP protocol and using JSON data encoding.

Number	TM Forum Open API	Download	Browse
TMF620	Product Catalog Management
TMF637	Product Inventory Management
TMF633	Service Catalog Management
TMF638	Service Inventory Management
TMF634	Resource Catalog Management
TMF639	Resource Inventory Management
TMF654	Prepay Balance Management
TMF635	Usage Management
TMF632	Party Management

Sigscale's Nrf_Rating API follows the 3GPP's drafting rules for 5GC Service Based Interfaces (SBI) and is aligned with the Nchf SBI for the 5GC Charging Function (CHF). It is derived directly from the Re interface DIAMETER application (partially) specified in (3GPP TS 32.296).

Name	Description	Download	Browse
Nrf	RF Rating Service

HTTP Methods

The HTTP methods used in this API include GET, HEAD, POST, PATCH and DELETE.

Media Types

Type Name
application/json
application/json-patch+json
application/merge-patch+json

Advanced Attribute Filtering Pattern

Complex queries are supported using a filter attribute as described in issue AP-832 of TM Forum API Project.

[Note: TMF630 Part 6 provides an equivalent advanced query syntax using JSON Path, however this implementation peredates that by several years. A future version shall provide JSON Path syntax support.]

Example:

	filter="[{usageCharacteristic.contains=[{name=nasIdentifier,value.like=[north-%]}]}]"

The right hand side (RHS) of the filter attribute should be enclosed in double quotes (""). Query values seperated by a comma (,) and treated as AND. A complex value should be enclosed in {}.

Operation	Description	LHS Data Type	RHS Data Type
.exact OR =	Equals (Case-sensitive)	String, Number, Date, Boolean	String, Number, Date, Boolean
.notexact OR <>	Not equal to (Case-sensitive)	String, Number, Date, Boolean	String, Number, Date, Boolean
.like	Match the patterns in the argument array, where "%" matches zero or more characters.	String	Array of String
.contains	Match LHS elements with RHS	Collection/Array	Array of String

Pagination

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

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

See rest_page_size and rest_page_timeout in the Configuration section below.

Pub/Sub Events

Event notification is supported as described in TMF630 Notification Patterns. An external entity may subscribe an API endpoint to receive event notifications for any of the Open APIs. A query portion may be included to limit the scope of subscribed events. Each eligible event will be sent to the endpoint in an HTTP POST operation.

[Note: A subscription will be silently removed on the first encountered error in sending a notification. The /hub collections may be be queried to verify that a subscription still exists.]

SNMP Agent

SigScale OCS supports fault & performance management 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.

IETF	MIB Name
	SIGSCALE-OCS-MIB
draft-ietf-dime-diameter-base-protocol-mib	SIGSCALE-DIAMETER-BASE-PROTOCOL-MIB
draft-ietf-dime-diameter-cc-appl-mib	SIGSCALE-DIAMETER-CC-APPLICATION-MIB
RFC4669	RADIUS-AUTH-SERVER-MIB
RFC4671	RADIUS-ACC-SERVER-MIB

Configuration

The ocs application may be configured using the following application environment variables.

Rating

min_reserve_octets

Centralized Unit Determination: minimum size of octets reserved. (default: 5000000)

min_reserve_seconds

Centralized Unit Determination: minimum size of seconds reserved, (default: 60)

min_reserve_messages

Centralized Unit Determination: minimum number of messages reserved. (default: 1)

charge_overflow

Leave negative balance Bucket when usage over credit. (default: true)

nrf_sub_id_type

Defines a list of Nrf subscription ID types, in order of priority, to use to find a SubscriberID to use for rating. The complete list is [imsi, msisdn, nai, gci, gli, iccid] (default: [imsi, msisdn])

nrf_valid_time

Threshold for time quota re-authorization in seconds. (default: undefined)

nrf_valid_volume

Threshold for volume quota re-authorization in octets. (default: undefined)

nrf_valid_unit

Threshold for service specific units quota re-authorization in number of units. (default: undefined)

quota_per_upf

5G data connectivity charging manages a quota for each UPF. (default: true)

Logging

acct_log_dir

Path of directory to store accounting logs.

acct_log_files

Number of accounting log files.

acct_log_rotate

Duration between IPDR logging.

acct_log_rotate_time

Time for IPDR log rotation: {H, M, S}.

acct_log_size

Size in bytes of accounting log files.

auth_log_dir

Path of directory to store authorization logs.

auth_log_files

Number of authorization log files.

auth_log_size

Size in bytes of authorization log files.

ipdr_log_dir

Path of directory to store IPDR logs.

export_dir

Path of directory to store exported files.

elastic_shipper

Shipper for Elastic Stack: {Url, Profile, Options} (default: undefined).

DIAMETER Configuration

diameter

Configuration groups for DIAMETER: {diameter, [{auth | acct, ip_address(), port(), [option()]}]}

'Origin-Host'

DiameterIdentity of this host. (default: inet:gethostname())

'Origin-Realm'

DiameterIdentity of this realm (default: inet_db:res_option(domain)).

'Host-IP-Address',

List of IP source addresses to be used.

'Auth-Application-Id'

List of IANA-assigned Application IDs. (default: [5,16777250,16777264,16777265])

capx_timeout

Deprecated. Equivalent to {listen, [{capx_timeout, Time}]}.

incoming_maxlen

Deprecated. Equivalent to {listen, [{incoming_maxlen, Len}]}.

pool_size

Deprecated. Equivalent to {listen, [{pool_size, Size}]}.

Poolsize of socket listeners.

watchdog_timer

Deprecated. Equivalent to {listen, [{watchdog_timer, Time}]}.

transport_module

Deprecated. Equivalent to {listen, [{transport_module, diameter_tcp}]}.

transport_config

Deprecated. Equivalent to {listen, [{transport_config, Options}]}.

listen

Transport options ([diameter:transport_opt()]) for a server listening for inbound connections.

connect

Transport options ([diameter:transport_opt()]) for a client making an outbound connection to a server.

eap_method_prefer

The EAP method which will be offered first. (default: akap)

eap_method_order

The list of EAP methods supported in order of preference. (default: [akap, aka, pwd, ttls])

nrf_uri

The Nrf_Rating API endpoint of a remote rating function (RF) (e.g. "http://example.net/nrf-rating/v1")

rf_class

The class of remote rating function (RF) to be used. Value b specifies a Class B RF with a colocated account balance management function (ABMF). If this option is not defined Class A operation is assumed with local RF and ABMF where any Product Offering Price may specify a remote RF as a pricing logic algorithm (PLA).

callback

The callback module to be used diameter events (default: ocs_diameter_3gpp_ro_application_cb)

sub_id_type

Defines a list of subscription ID types, in order of priority, to use to find a SubscriberID to use for rating. The complete list is [imsi, msisdn, nai, sip, private] (default: [msisdn])

RADIUS Configuration

radius

Configuration groups for RADIUS: {radius, [{auth | acct, ip_address(), port(), [option()]}]}

eap_method_prefer

The EAP method which will be offered first. (default: akap)

eap_method_order

The list of EAP methods supported in order of preference. (default: [akap, aka, pwd, ttls])

sock_opts

UDP socket options. (gen_udp:option())

HTTP Configuration

tls_cert

Public certificate for TLS over EAP.

tlst_key

Private key for TLS over EAP.

tls_cacert

Certificate Authority certificate for TLS over EAP.

rest_page_size

Defines the maximum number of items to return for a REST collection.

oauth_audience

Defines the recipient for who the JWT is intended: {string()}

oauth_issuer

Defines the issuer of the JWT: {string()}

oauth_key

Path of the file containing a publicKey in PEM format: {string()}

{port, integer()}

The port that the HTTP server listen to.

{server_root, path()}

Defines the home directory of the server.

{document_root, path()}

Defines the top directory of the frontend HTML files.

{directory, {path(), [{property(), term()}]}}

The properties for directories include:

{auth_type, plain | dets | mnesia}

Authentication table storage. (use mnesia)

{auth_name, string()}

Sets the authorization realm for path().

{require_user, [string()]}

Defines list of users to grant access to path().

{require_group, [string()]}

Defines list of groups to grant access to path().

3GPP AAA Server Configuration

hss_realm

Enable SWx interface to a Home Subscriber Server (HSS) realm: {hss_realm, string()}

hss_host

SWx interface to a specific HSS host: {hss_host, string()}

aka_kpseu

Encryption keys used for the generation of temporary identities: {aka_kpseu, [{KeyIndicator :: 0..15, Key :: binary()}]} (default: [{1, <<0:128>>}])

aaa_failure

Default value for AAA-Failure-Indicator in MAR on SWx: {aaa_failure, boolean()} (default: false)

Example sys.config

[{ocs,
      [{radius,
               [{auth,
                     [{{0,0,0,0}, 1812,
                            [{eap_method_prefer, pwd},
                            {eap_method_order, [pwd, ttls]}]}]},
               {acct,
                     [{{0,0,0,0}, 1813, []}]}]},
      {diameter,
               [{acct,
                      [{{0,0,0,0}, 3868, []}]},
               {auth,
                     [{{0,0,0,0}, 3869,
                           [{eap_method_prefer, aka},
                           {eap_method_order, [aka, akap, pwd]}]},
                     {{0,0,0,0}, 0,
                           [{connect,
                                 [{raddr, {172,16,1,2}},
                                 {rport, 3868}]}]}]}]},
		{hss_realm, "epc.mnc001.mcc001.3gppnetwork.org"},
      {min_reserve_octets, 5000000},
      {min_reserve_seconds, 60},
      {min_reserve_messages, 1},
      {acct_log_rotate, 1440},
      {acct_log_dir, "log/acct"},
      {acct_log_files, 100},
      {auth_log_dir, "log/auth"},
      {auth_log_size, 10485760},
      {auth_log_files, 100},
      {ipdr_log_dir, "log/ipdr"},
      {export_dir, "log/export"},
      {rest_page_size, 1000},
      {tls_key, "ssl/key.pem"},
      {tls_cert, "ssl/cert.pem"},
      {tls_cacert, "ssl/ca.pem"},
      {oauth_audience, "account"},
      {oauth_issuer, "sigscale"},
      {oauth_key, ssl/sigscale.pem}]},
{radius,
      [{sock_opts, [{recbuf, 131072}, {sndbuf, 131072}]}]},
{snmp,
      [{agent,
           [{config, [{dir, "snmp/conf"}]},
           {db_dir, "snmp/db"}]}]},
{inets,
      [{services,
         [{httpd,
            [{server_name, "ocs"},
            {directory_index, ["index.html"]},
            {directory, {"/",
                  [{auth_type, mnesia},
                  {auth_name, "ocs.sigscale.org"},
                  {require_group, ["staff"]}]}},
            {transfer_disk_log, "/usr/lib/erlang/lib/ocs-3.4.54/log/http/transfer"},
            {security_disk_log, "/usr/lib/erlang/lib/ocs-3.4.54/log/http/security"},
            {error_disk_log, "/usr/lib/erlang/lib/ocs-3.4.54/log/http/error"},
            {transfer_disk_log_size, {10485760, 10}},
            {error_disk_log_size, {10485760, 10}},
            {error_disk_log_size, {10485760, 10}},
            {security_disk_log_size, {10485760, 10}},
            {disk_log_format, internal},
            {modules,
                  [mod_alias,
                  mod_auth,
                  mod_disk_log,
                  mod_responsecontrol,
                  mod_ocs_rest_accepted_content,
                  mod_ocs_rest_get,
                  mod_get,
                  mod_ocs_rest_head,
                  mod_ocs_rest_post,
                  mod_ocs_rest_patch,
                  mod_ocs_rest_delete]},
            {port, 8080},
            {socket_type, {essl,
                  [{certfile,  "/etc/ssl/certs/ocs.pem"},
                  {keyfile, "/etc/ssl/private/ocs.pem"}]}},
            {server_root, "/home/ocs"},
            {alias, {"/doc", "/usr/lib/erlang/lib/ocs-3.4.54/doc"}},
            {document_root, "/usr/lib/erlang/lib/ocs-3.4.54/priv/www"}]}]}]}].

Overview

Generated by EDoc