Section 6. Radiator OCS configuration

6.1. <AuthBy DiaOCS>

A DiaOCS clause defines OCS which handles Diameter Gy requests originated by a PCEF running on a GGSN, PDN GW or other gateway.

The OCS in Radiator has been designed to be modular and uses a number modules to process the Diameter Gy messages, fetch and update information in the OCS database and store Gy session information. These modules are configured with separate clauses and referenced by their identifier from <AuthBy DiaOCS> clause.

A number of hooks are defined to customise the action when, for example, quota thresholds are reached, quota runs out or quota is used for the first time. The operators are encouraged to develop their own functions and Perl modules to handle the different events.

6.1.1. OCSGy

The Identifier of <OCSGy> clause to use for processing Diameter Gy messages. OCSGy module is required to read information from Gy requests and add information to Gy answers. This allows separating the OCS logic from Diameter messages details.

6.1.2. OCSDB

The Identifier of clause that defines a database for OCS. For example, the SQL based OCS DB shipped with Radiator policy and charging support modules is configured with <OCSDBSQL> clause.

The SPR clause must implement the interface defined by the OCSDBGeneric.pm module. The backend is not limited to SQL but can be LDAP or any repository that can hold subscriber information.

6.1.3. OCSGySession

The Identifier of clause that defines a Gy session repository. For example, the SQL based OCSGySession module shipped with Radiator policy and charging support modules is configured with <OCSGySessionSQL> clause.

The OCSGySession clause must implement the interface defined by the GySessionGeneric.pm module. The backend is not limited to SQL but should use a a backend that supports frequent creation and updating of session data.

6.1.4. FirstUseHook

This hook will be called when the subscriber's quota still at the initial value and DCC (Diameter Credit-Control) message is received. The quota is initialised typically when during the first use or subsequently when the remaining quota is initialised by provisioning system or for some other external reason.

The default hook will log the event, but you may change the hook to call send SMS, call an external process or do any other action.

The following arguments are passed to the hook in the following order:

Reference to this AuthBy
Reference to the current OCSmsg
Amount of quota left after this reservation

6.1.5. QuotaUseHook

This hook will be called for each Multiple-Services-Credit-Control attribute that reports unit usage. There is no default.

The following arguments are passed to the hook in the following order:

Reference to this AuthBy
Reference to the current OCSmsg
Hash ref with the allocation type, rating group, service identifier, and other values related to the M-S-C-C and its allocation

6.1.6. FinalUnitHook

This hook will be called for each Multiple-Services-Credit-Control attribute that returns final units to the PCEF. The default is to add Final-Unit-Indication with Final-UnitAction = TERMINATE.

The following arguments are passed to the hook in the following order:

Reference to this AuthBy
Reference to the current OCSmsg
Reference to the current Multiple-Services-Credit-Control attribute that has Service-Identifier and Rating-Group filled in, where applicable

6.1.7. Thresholds

This optional parameter allows you to define threshold percentages that trigger ThresholdHook.

Example

# Trigger ThresholdHook when half and little remaining
Thresholds 50, 10

6.1.8. ThresholdHook

This hook will be called when the subscriber's quota reaches one or more threshold percentages defined in the configuration.

The default hook will log the event, but you may change the hook to call send SMS, call an external process or do any other action.

Note

If multiple thresholds are reached during the quota allocation, the ThresholdHook will be called once for each threshold. The order of calls depends on the order the thresholds are configured with the Thresholds parameter.

The following arguments are passed to the hook in the following order:

Reference to this AuthBy
Reference to the current OCSmsg
Threshold percentage that was reached
Quota percentage before allocation but after unused bytes from previous allocation have been credited
Quota percentage after allocation

6.1.9. ValidityTime

ValidityTime defines the quota validity time in seconds. If this option is not defined, Validity-Time attribute is not included in the CCA and the client will use its default value. There is no default value.

Example

# Instruct the client report no later than after 10 minutes
ValidityTime 600

6.1.10. TccMultiplier

This optional parameter defines the multiplier used with ValidityTime to derive Tcc timer value for Gy session supervision. Defaults to 2.

Example

# Tcc timer expires a bit later than RFC suggests
TccMultiplier 2.1

6.1.11. TccTimer

When TccTimer is defined, it will set the value of Tcc timer in seconds directly ignoring the possible TccMultiplier. When Tcc timer is set to 0 with TccTimer or combination of ValidityTime and TccMultiplier, or TccCheckInterval is 0, Radiator will not do Gy session supervision. TccTimer is not defined by default.

Example

# Tcc timer is 1200. No dependency on the other variables
TccTimer 1200

6.1.12. TccCheckInterval

Interval in seconds to run Tcc timer checks. This affects only how often the checks are run. It does not affect how the Tcc timer value is calculated for Gy session supervision. When the TccCheckInterval is set to 0, Radiator will not do Gy session supervision allowing an external process to supervise the sessions. The default is 30 seconds.

Example

# Check the Tcc timer expiries one a minute
TccCheckInterval 60

6.1.13. QuotaHoldingTime

Interval in seconds to run Tcc timer checks. This affects only how often the checks are run. It does not affect how the Tcc timer value is calculated for Gy session supervision. When the TccCheckInterval is set to 0, Radiator will not do Gy session supervision allowing an external process to supervise the sessions. The default is 30 seconds.

Example

# Check the Tcc timer expiries one a minute
TccCheckInterval 60

6.1.14. Triggers

Triggers defines the Trigger AVP contents returned with INITIAL_REQUEST CCA. Empty value is permitted causing empty Trigger AVP to be sent. If the option is not defined, which is the default, then Trigger AVP is not included in the CCA and the client defaults are used.

Example

# Disable all triggers
Triggers

6.1.15. SessionFailover

When SessionFailover is set, Radiator will add CC-Session-Failover in CCA messages. The possible values are: FAILOVER_NOT_SUPPORTED and FAILOVER_SUPPORTED. SessionFailover is not set by default, and hence the clients default to FAILOVER_NOT_SUPPORTED.

Example

# Tell clients we support failover
SessionFailover FAILOVER_SUPPORTED

6.1.16. FailureHandling

When FailureHandling is set, Radiator will add Credit-Control-Failure-Handling in CCA messages. The possible values are: TERMINATE, CONTINUE, and RETRY_AND_TERMINATE. FailureHandling is not set by default, and hence the clients default to TERMINATE.

Example

# Tell clients they can try our other instances
FailureHandling RETRY_AND_TERMINATE

6.2. <OCSGy>

OCSGy module processes incoming Diameter Gy messages and adds any attributes required by allocations and other processing done by OCS.

The other modules used by <Auth DiaOCS> do not directly use Diameter Gy messages.

6.2.1. Identifier

This optional parameter allows you to assign a symbolic name which is used by <AuthBy DiaOCS> clause OCSGy parameter.

6.3. <OCSDBSQL>

The OCSDB (Online Charging System Database) that is shipped with Radiator policy and charging support uses SQL for storing the information.

OCSDBSQL implements the interface defined by OCSDBGeneric.pm which allows creating customised OCSDB that uses, for example, LDAP as the repository.

6.3.1. Identifier

This optional parameter allows you to assign a symbolic name which is used by <AuthBy DiaOCS> SPR parameter.

6.3.2. SubscriberSelectE164

Defines the SQL statement that is called to find and fetch subscriber information based on the end user's E.164.

6.3.3. SubscriberSelectIMSI

Defines the SQL statement that is called to find and fetch subscriber information based on the end user's IMSI.

6.3.4. SubscriberSelectPRIVATE

Defines the SQL statement that is called to find and fetch subscriber information based on the end user's private identifier.

6.3.5. SubscriberSelectById

Defines the SQL statement that is called to find and fetch subscriber information based on the end user's ID in the subscriber table. Used for example, when the ID is stored in the GxSession repository.

6.3.6. SubscriberSelectParam

This parameter specifies the bind variables to be used with all SubscriberSelect* statements. %0 is replaced by end user's E.164, IMSI, SIP URI, NAI, or ID based on which type of identity is used to lookup the subscriber.

6.3.7. SubscriberColumnDef

This parameter allows you to define the way Radiator interprets the result of the SubscriberSelect* statements.

You can specify any number of SubscriberColumnDef parameters, one for each interesting field returned by SubscriberColumnSelect. The general format is:

SubscriberColumnDef n, dataitem

n is the index of the field in the result of SubscriberSelect*. 0 is the first field.
dataitem is the name of a entry in the subscriber information

The subscriber information entries required by the modules shipped with Radiator policy and charging support use the following information:

Table 11. Subscriber information fetched from the OCSDB

Name	Description
`id`	Index or other identifier that uniquely identifies the subscription in the OCSDB
`e164`	E.164 formatted telephone number for the user
`imsi`	IMSI for the user
`nai`	NAI for the user
`private`	Private identifier for the user
`enabled`	Value the evaluates as true in Perl means the subscription is enabled
`initial_quota`	Initial quota for the subscriber
`quota`	Currently remaining quota
`all_reservations`	Quota that is currently reserved across all active Gy sessions

6.3.8. ServiceSelect

Defines the SQL statement to fetch all supported services.

6.3.9. ServiceColumnDef

This parameter allows you to define the way Radiator interprets the result of the ServiceSelect statement.

You can specify any number of ServiceColumnDef parameters, one for each interesting field returned by ServiceSelect. The general format is:

ServiceColumnDef n, dataitem

n is the index of the field in the result of ServiceSelect. 0 is the first field.
dataitem is the name of a entry in the PCC rule information

The service information entries required by the modules shipped with Radiator policy and charging support use the following information:

Table 12. Service information fetched from the OCSDB

Name	Description
`id`	Index or other identifier that uniquely identifies this service in the OCSDB
`name`	Free form description of this service for humans. Not used with Gy protocol.
`service_identifier`	Value of `Service-Identifier` attribute in Gy messages
`default_allocation`	How many service units are allocated for the service by default
`unit_type`	Currently supported value is `TOTAL_OCTETS`
`unit_price`	Price for one `unit_type`
`rating_group`	Defined as value of `Rating-Group` attribute if service belongs to a rating group. `NULL` or empty otherwise
`pool_identifier`	Defined as value of `G-S-U-Pool-Identifier` attribute if service belongs to a pool. `NULL` or empty otherwise

6.3.10. RatingGroupSelect

SQL statement to fetch all supported rating groups.

6.3.11. RatingGroupColumnDef

This optional parameter allows you to define the way Radiator interprets the result of the RatingGroupSelect statement.

You can specify any number of RatingGroupColumnDef parameters, one for each interesting field returned by RatingGroupSelect. The general format is:

RatingGroupColumnDef n, dataitem

n is the index of the field in the result of RatingGroupSelect. 0 is the first field.
dataitem is the name of a entry in the data plan information

The service information entries required by the modules shipped with Radiator policy and charging support use the following information:

Table 13. Rating group information fetched from the OCSDB

Name	Description
`id`	Index or other identifier that uniquely identifies this rating group in the OCSDB
`name`	Free form description of this rating group for humans. Not used with Gy protocol.
`rating_group`	Value of `Rating-Group` attribute in Gy messages
`default_allocation`	How many service units are allocated for the rating group by default
`unit_type`	Currently supported value is `TOTAL_OCTETS`
`unit_price`	Price for one `unit_type`
`pool_identifier`	Defined as value of `G-S-U-Pool-Identifier` attribute if the rating group belongs to a pool. `NULL` or empty otherwise

6.3.12. PoolSelect

SQL statement to fetch all supported pool definitions.

6.3.13. PoolColumnDef

This optional parameter allows you to define the way Radiator interprets the result of the PoolSelect statement.

You can specify any number of PoolColumnDef parameters, one for each interesting field returned by PoolSelect. The general format is:

PoolColumnDef n, dataitem

n is the index of the field in the result of PoolSelect. 0 is the first field
dataitem is the name of a entry in the subscriber information

The usage tracking information entries required by the modules shipped with Radiator policy and charging support use the following information:

Table 14. Pool information fetched from the OCSDB

Name	Description
`id`	Index or other identifier that uniquely identifies this pool in the OCSDB
`name`	Free form description of this pool for humans. Not used with Gy protocol.
`pool_identifier`	Value of `G-S-U-Pool-Identifier` attribute for this pool
`default_allocation`	How many service units are allocated for the pool by default
`exponent`	Value of Exponent in the `Unit-Value` attribute for this pool

6.3.14. RefreshPeriod

RefreshPeriod specifies the time period in seconds that OCSDBSQL will refresh the service, rating group and pool definitions by rereading the database. If set to 0, then OCSDBSQL will only read the definitions from the database at startup and on SIGHUP. Defaults to 0.

Example

# Refresh the informations two times a day
RefreshPeriod 43200.

6.4. <OCSGySessionSQL>

<OCSGySessionSQL> stores information about subscribers' Gy sessions and reservations within sessions in SQL. The Gy session table has one row for each active session. For each service, rating group and pool reservation within a session, one row is created to hold the allocation information. By default session and allocation information is kept after the session is finished providing history information about all Gy sessions.

<OCSGySessionSQL> implements the interface defined by OCSGySessionGeneric.pm which allows creating customised Gy session repositories.

6.4.1. Identifier

This optional parameter allows you to assign a symbolic name which is used by AuthBy DiaOCS GySession parameter.

6.4.2. AddSessionQuery

SQL query to add a new session after Gy INITIAL_REQUEST is received.

6.4.3. AddSessionQueryParam

This parameter specifies the bind variables to be used with AddSessionQuery. The values for %0 - %7 come from OCSmsg.

6.4.4. UpdateSessionQuery

SQL query to run when Gy UPDATE_REQUEST is received.

6.4.5. UpdateSessionQueryParam

This parameter specifies the bind variables to be used with UpdateSessionQuery. %0 is the ID fetched with GetSessionSelect. %1 is the quota reservation change for this session.

6.4.6. CloseSessionQuery

SQL query to run when Gy TERMINATION_REQUEST is received.

6.4.7. CloseSessionQueryParam

This parameter specifies the bind variables to be used with CloseSessionQuery. %0 is the id fetched with GetSessionSelect.

6.4.8. GetSessionSelect

SQL query to fetch information about a Gy session.

6.4.9. GetSessionSelectParam

This parameter specifies the bind variables to be used with GetSessionSelect. %0 is replaced by the Diameter Session-Id attribute value.

6.4.10. GetSessionColumnDef

This optional parameter allows you to define the way Radiator interprets the result of the GetSessionSelect statement.

You can specify any number of GetSessionColumnDef parameters, one for each interesting field returned by GetSessionSelect. The general format is:

GetSessionColumnDef n, dataitem

n is the index of the field in the result of GetSessionSelect. 0 is the first field.
dataitem is the name of a entry in the subscriber information

The subscriber information entries required by the modules shipped with Radiator policy and charging support use the following information:

Table 15. Session information fetched from the GySession

Name	Description
`id`	Index or other identifier that uniquely identifies this session in the Gy Session
`start_time`	Unix timestamp for the session start
`reserved_quota`	Quota currently reserved for this session
`subscription_id`	Value of id identifying the subscriber as fetched by OCSDB
`session_id`	`Session-Id` for this Gy session
`imsi`	IMSI for the subscriber
`nai`	NAI for the subscriber
`e164`	E.164 formatted telephone number for the subscriber

6.4.11. TccQuery

SQL query to fetch and optionally close sessions for which the Tcc timer has expired.

6.4.12. TccQueryParam

This parameter specifies the bind variables to be used with TccQuery. %0 is the Unix timestamp adjusted by Tcc timer value from

Auth
                     DiaOCS

.

6.4.13. TccCleanupQuery

SQL query to process sessions for which Tcc timer has expired. If the query is not defined, it will not be run allowing TccQuery to do the clean up.

6.4.14. TccCleanupQueryParam

This parameter specifies the bind variables to be used with TccCleanupQuery. %0 is the Unix timestamp adjusted by Tcc timer value from

Auth
                     DiaOCS

.

6.4.15. AddAllocationQuery

SQL query to add one allocation for a Gy session. An allocation is done when quota is reserved for a service, rating group or a pool. For pooled allocations, one allocation is added to describe the whole pool and one allocation is added for each pooled service and rating group.

6.4.16. AddAllocationQueryParam

This parameter specifies the bind variables to be used with AddAllocationQuery.

%0 is the id fetched with GetAllocationsSelect
%1 tells if this reservation is for a session, rating group or pool
%2 is the Service-Identifier
%3 is the Rating-Group
%4 is the number of the reserved service units
%5 is the amount of quota corresponding to the reserved service units
%6 is the pool identifier which identifies the information about a pool in OCSDB

6.4.17. UpdateServiceAllocationQuery

SQL query to update a service based allocation for a Gy session.

6.4.18. UpdateServiceAllocationQueryParam

This parameter specifies the bind variables to be used with UpdateServiceAllocationQuery.

%0 is the id fetched with GetAllocationsSelect
%1 is the Service-Identifier
%2 is the Rating-Group
%3 is the number of the reserved service units
%4 is the amount of quota corresponding to the reserved service units
%5 is the pool identifier which identifies the information about a pool in OCSDB

6.4.19. UpdateRGAllocationQuery

SQL query to update a rating group based allocation for a Gy session. Behaves the same as UpdateServiceAllocationQuery and uses UpdateRGAllocationQueryParam with the same special values as defined for UpdateServiceAllocationQueryParam.

6.4.20. UpdatePoolAllocationQuery

SQL query to update a rating group based allocation for a Gy session. Behaves the same as UpdateServiceAllocationQuery and uses UpdateRGAllocationQueryParam with the same special values as defined for UpdateServiceAllocationQueryParam.

6.4.21. GetAllocationsSelect

SQL query to run when information about all active allocations for a Gy session is needed.

6.4.22. GetAllocationsSelectParam

This parameter specifies the bind variables to be used with GetAllocationsSelect. %0 is replaced by the Diameter Session-Id attribute value.

6.4.23. GetAllocationsColumnDef

This optional parameter allows you to define the way Radiator interprets the result of the GetAllocationsSelect statement.

You can specify any number of GetSessionColumnDef parameters, one for each interesting field returned by GetSessionSelect. The general format is:

GetAllocationsColumnDef n, dataitem

n is the index of the field in the result of GetAllocationsSelect. 0 is the first field.
dataitem is the name of a entry in the subscriber information

The subscriber information entries required by the modules shipped with Radiator policy and charging support use the following information:

Table 16. Allocation information fetched from the GySession

Name	Description
`id`	Index or other identifier that uniquely identifies this allocation in the Gy session
`allocation_type`	Is this allocation for a service, rating group or pool
`service_identifier`	Has a non-empty and non-NULL value for service allocation
`rating_group`	Has a non-empty and non-NULL value for rating group allocation
`pool_identifier`	Has a non-empty and non-NULL when the service or rating group is a pool member or the allocation describes the pool
`service_units`	The number of units allocated for this service or rating group. Note Not meaningful for allocation the describes a pool
`allocated_quota`	The amount of quota this the `service_units` reserve
p`ool_identifier`	Has a non-empty and non-NULL when the service or rating group is a pool member or the allocation describes the pool

6.4.24. CloseAllocationQuery

SQL query to run when this allocation is not in use anymore.

6.4.25. CloseAllocationQueryParam

This parameter specifies the bind variables to be used with CloseAllocationQuery. %0 is the allocation ID.