Warning These simulators are "legacy" tools, which were provided to give the example services something to connect to. They have been superseded by the new Scenario Simulator tool, which provides significantly more functionality and flexibility. They are still distributed with the package because the Diameter Scenario Pack does not yet include scenarios that match the bundled examples.

Topics

This guide covers the following topics, for these simulators:

Simulator What it’s for

a Charging Data Function simulator that accepts connections and responds to every Diameter Base Accounting and Diameter Rf Accounting-Request with an Accounting-Answer

a Home Subscriber Server simulator that provides basic functionality for testing Diameter Sh requests

an Online Charging System simulator that supports the Diameter Credit Control Application (CCA) and Diameter Ro based billing.

Diameter CDF Simulator

The CDF Simulator is a Diameter server that accepts connections and responds to every Accounting-Request with an Accounting-Answer. Its standard behaviour is to build a CDR based on the incoming ACRs, then write it to disk when the final ACR for a session is received; but it can be extended in two ways:

  • by providing a CDR builder class that will be invoked to create and update CallDetailRecord objects before they are written to disk

  • by providing an Accounting-Request handler class that will be invoked when an Accounting-Request is received from the client.

It can handle Diameter Rf and Diameter Base Accounting requests.

Starting the simulator

Use the following command to start the simulator for Diameter Rf:

./cdf-simulator.sh

Use the following command to start the simulator for Diameter Base Accounting:

./acct-simulator.sh
Note You can use the -i switch to set operations to be traced and written out (to the console in the default logging configuration) at the INFO log level.

Configuring the simulator

The configuration for the simulator is in config/cdf.properties.

Warning The configuration values only need to be changed if different behaviour is needed; otherwise they can be left at their defaults.

Properties you can configure include: Diameter stack configuration, Extension AVPs, Custom extensions, Artificial latency, and RA configuration.

Diameter stack configuration

The configuration for the Diameter stack must be provided.

Property What it specifies

cdf.diameterconfig.file

File to load configuration profile from (Rhino export format).

cdf.diameterconfig.profileid

Diameter stack configuration profile name in format "TableName/ProfileName"

Extension AVPs

The resource adaptor embedded in the simulator can be configured to handle extension AVPs using the same mechanism as an RA deployed in Rhino (see Configuring Diameter Resource Adaptors). The profile data should be provided in the format created by exporting profiles from Rhino using the standard export feature. The configuration properties used to specify these files and the name of the profile are:

Property What it specifies

cdf.extensionprofile.files

Files to load profiles from (Rhino export format, comma-delimited list).

cdf.extensionprofile.profileid

Profile ID to use from files above.

Custom extensions

There are two configuration properties that can be used to specify the custom handling for the incoming requests. (See also Customising simulator behaviour.)

Property What it specifies

cdf.cdrbuilder

Custom CDR builder class (must implement CdrBuilder interface).

cdf.acrhandler

Custom Accounting Requests handler class (must implement AccountingRequestHandler interface).

Artificial latency

The simulator can be configured to introduce a latency into operations, to better simulate a real system. The delays introduced will be randomly generated to have a normal distribution with the specified mean and standard deviation. As a rule of thumb, the standard deviation should be no more than 1/4 of the mean.

Property What it specifies Default

cdf.responselatency.mean

The mean value of the artificially introduced latency.

300

cdf.responselatency.stddev

The standard deviation of the latency.

50

RA configuration

The two configuration properties described for the Diameter Rf Resource Adaptor can be specified for the simulator.

Property What it specifies

rf.statefulsessiontimeout

Value for RA configuration property StatefulSessionTimeout.

rf.acctinteriminterval

Value for RA configuration property AccountingInterimInterval.

Configuring logging

The default logging configuration is write-abbreviated INFO-level output to the console, and DEBUG-level output to a file named cdfsimulator.log.

To change this configuration, edit the log4j.properties file in the config directory.

Warning The logging subsystem is also used to write the CDRs to disk. This configuration is clearly marked in the configuration file and should be changed with caution.

Customising simulator behaviour

The 3GPP specification for Diameter Rf defines over 100 different AVPs that may be contained in an Rf Accounting-Request message. The OpenCloud CDF simulator therefore includes a mechanism for users of the simulator to have full control over the values that are retrieved from the request message and written to the CDRs. It does this by allowing custom classes to be specified and included in the classpath for the simulator that will be loaded at runtime.

Below are details for:

Implementing a custom CDR builder

This customisation provides the ability to plug in a class to create custom Call Detail Records from the Accounting-Request messages that are received. Custom CDR builders must implement the CdrBuilder interface. The CallDetailRecord class can be extended as necessary.

The responsibility of a CdrBuilder implementation is to create and update CDR records; it should not write to any file itself.

For an accounting session, the openCdr() method will be called for the first ACR (Accounting-Record-Type = START_RECORD) and should return a new CallDetailRecord object. This same object will then be passed as an argument to updateCdr() on subsequent ACRs (Accounting-Record-Type = INTERIM_RECORD) and also to closeCdr() on the final ACR (Accounting-Record-Type = STOP_RECORD) so it can be updated before being written.

The default request handler will then write the CDR to cdr.txt, using Log4J as configured by the log4j.properties file.

Here is part of the built-in AccountingRequestHandler implementation as a reference:

public void handleAccountingRequest(AccountingRequest acr, AccountingAnswer aca) {

    AccountingRecordType accountingRecordType = acr.getAccountingRecordType();

    if(accountingRecordType == AccountingRecordType.START_RECORD) {
        CallDetailRecord cdr = builder.openCdr(acr);
        // [...] save CDR
    }
    else if(accountingRecordType == AccountingRecordType.INTERIM_RECORD) {
        // [...] retrieve CDR for this session
        builder.updateCdr(cdr, acr);
    }
    else if(accountingRecordType == AccountingRecordType.STOP_RECORD) {
        // [...] retrieve CDR for this session
        builder.closeCdr(cdr, acr);
        cdrWriter.writeCdr(cdr);
    }

    // [...] set result code etc before sending ACA
}

Implementing a custom accounting-request handler

This customisation provides even more control over the handling of incoming requests. Custom Accounting-Request handlers must implement the AccountingRequestHandler interface to handle the requests.

Note that the CDR builder won’t be used in this case since that behaviour is part of the standard Accounting-Request handling behaviour.

Building and installing customisations

To build a customisation for the simulator, you simply need to compile the class against the cdf-simulator.jar file. For example, if the class is named com.customer.CustomCdrBuilder in the ext-src directory, the following command (all on one line) will compile it into the classes directory:

javac -classpath cdf-simulator.jar -d classes ext-src/com/customer/CustomCdrBuilder.java

To add it to the classpath of the simulator, simply edit the CLASSPATH variable in cdf-simulator.sh to include the classes directory.

Finally, the config/cdf.properties file should be updated to include the name of the class.

Diameter HSS Simulator

The Home Subscriber Server (HSS) simulator provides an interface for Diameter Sh testing only. It does not simulate all interfaces provided by a full HSS. It also does not provide full support for user-data manipulation.

Simulator modes

The HSS simulator can be run two different modes:

  1. Non-persistent — Accounts are read from a file at startup and never written back to the filesystem. All account updates are lost when the simulator is stopped.

  2. Persistent — A database is used. Data files must be provided to populate the tables with initial data. Accounts persist across simulator restarts.

Starting the simulator

Use the following commands to start the simulator:

Mode Command

Non-persistent

 
./hss-simulator.sh

Persistent

First time, to populate database:

./hss-simulator.sh -db -a config/accounts.xml

With a populated database:

./hss-simulator.sh -db

Configuring the database

To control whether the database is started in-process or connected to through a socket, see the hss-database.properties file. This file contains comments that describe how to start and configure the hsqldb database.

Adding artificial latency

The simulator can be configured to introduce a delay before responding to a request, to better simulate a real server. The delays introduced will be generated to have a normal distribution with the specified mean and standard deviation. As a rule of thumb, the standard deviation should be no more than 1/4 of the mean.

Switch What it sets Default

-l

mean value of the artificially introduced latency, in ms

300

-v

standard deviation of the latency, in ms

50

Configuring logging

The default logging configuration is write-abbreviated INFO-level output to the console, and DEBUG-level output to a file named hss-simulator.log.

To change this configuration, edit the log4j.properties file in the config directory.

Diameter OCS Simulator

The OCS simulator is a Diameter server that accepts connections and responds to every Credit-Control-Request with a Credit-Control-Answer.

This simulator supports either Diameter CCA or Diameter Ro depending on which script is used to start the simulator. The differences between the Diameter Ro variant and Diameter CCA variant are:

  • where credit control AVPs must be located (within a Multiple-Services-Credit-Control for Ro and on the message for CCA)

  • the log file name

  • the database properties file name.

Starting the simulator

Use the following command to start the simulator for Diameter Ro:

./ro-simulator.sh

Use the following command to start the simulator for Diameter CCA:

./dcca-simulator.sh
Note You can use the -i switch to set operations to be traced and written out (to the console in the default logging configuration) at the INFO log level.

Starting the simulator without any switches will cause it to use non-persistent mode with the rates and accounts loaded from default file locations.

Simulator modes

The OCS simulator can be run two different modes:

  1. Non-persistent — Rates and accounts are read from a file at startup and never written back to the filesystem. All account updates are lost when the OCS simulator is stopped.

  2. Persistent — A database is used. Data files must be provided to populate the tables with initial data. Account balances persist across simulator restarts.

Starting the simulator

Use the following commands to start the simulator:

Mode Command

Non-persistent

 
./dcca-simulator.sh

Persistent

First time, to populate database:

./dcca-simulator.sh -db -r config/rates.xml -a config/accounts.xml

With a populated database:

./dcca-simulator.sh -db

Configuring the database

To control whether the database is started in-process or connected to using a socket, see the dcca-database.properties file. This file contains comments that describe how to start and configure the hsqldb database.

Adding artificial latency

The simulator can be configured to introduce a delay before responding to a request, to better simulate a real online charging system. The delays introduced will be generated to have a normal distribution with the specified mean and standard deviation. As a rule of thumb, the standard deviation should be no more than 1/4 of the mean.

Switch What it sets Default

-l

mean value of the artificially introduced latency, in ms

300

-v

standard deviation of the latency, in ms

50

Setting other options

Switch What it sets

-g

Generates an account for every subscriber in the range(s) specified. Use hyphens to specify ranges, commas to separate them. For example: 021320000-021320999,021420000-021420999 will create 2000 accounts.

-b

Sets the initial balance for accounts created using the -g switch.

-i

Sets all charging operations to be traced and written out (to the console in the default logging configuration) at the INFO log level.

Configuring logging

The default logging configuration is write-abbreviated INFO-level output to the console, and DEBUG-level output to a file named dccasimulator.log. To change this configuration, edit the log4j.properties file in the config directory.