This document describes and tells how to deploy, configure, and manage the OpenCloud Diameter Resource Adaptor package.

About the Diameter Resource Adaptors package

The Diameter Resource Adaptors package contains all the OpenCloud resource adaptors that are based on the Diameter protocol. The supported Diameter applications are the IETF standards for Diameter Accounting and Credit Control, as well as the 3GPP Reference Points Ro, Rf, Sh and Gx. The Diameter Base resource adaptor can be used to send and receive arbitrary Diameter messages, allowing custom Diameter applications to be implemented.

The package also includes example services that use the resource adaptors, and simulators to run the examples against.

Topics

This document includes the following topics:

About the Diameter Resource Adaptors

  • an overview of the Diameter Resource Adaptors package

  • responsibilities of the resource adaptor and services

  • resource adaptor type API design

  • sending and receiving non-standard AVPs and messages

Deploying the Diameter Resource Adaptors

  • how to deploy the Diameter resource adaptors

Configuring Diameter Resource Adaptors

  • how to configure the resource adaptors using profiles and properties

  • how to configure extension AVPs

Diameter Credit Control Fault Tolerance

  • configuration and behaviour of resource adaptors in fault-tolerant mode

Example Diameter Services

  • how to install and run the example services for each Diameter resource adaptor

Other documentation for the Diameter Resource Adaptors can be found on the Diameter Resource Adaptors product page.

About the Diameter Resource Adaptors

The OpenCloud Diameter resource adaptors manage Diameter peer connections and provide SLEE services with the ability to send and receive Diameter messages.

Below are an overview of the responsibilities of the RA and services, resource adaptor type API summary, sending and receiving non-standard AVPs and messages, and a description of the context of the Diameter Resource Adaptor package.

Resource adaptor responsibilities

The resource adaptor is responsible for the following aspects of the Diameter protocol:

  • Initiate and maintain peer connections configured in peer table.

  • Route and load-balance outgoing messages according to the realm table and configuration properties.

  • Send outgoing connection-related Diameter messages (CER/CEA, DWR/DWA, DPR/DPA).

  • Process incoming connection-related Diameter messages (includes CUR, see RFC6737).

  • Start and end SLEE activities for Diameter sessions where applicable.

  • Encode Java objects into Diameter’s on-the-wire encoding.

  • Decode incoming messages and create equivalent Java objects.

  • Optionally replicate activities to support credit control session failover.

This leaves the service needing only to: construct Java objects for application-level Diameter messages and submit them to the resource adaptor; and process application-level Diameter messages received as Java objects in SLEE events.

Resource adaptor type API summary

The Diameter resource adaptor type API includes these features:

  • Each Diameter resource adaptor type contains a comprehensive mapping of the Diameter messages and grouped AVPs defined by the applicable specification. Every message and grouped AVP is represented by a Java interface with bean-style access methods.

  • Enumerated types defined by the specification are provided as Java constant objects.

  • The provider interface has methods to create activities and send messages synchronously.

  • Activity interfaces contain methods to send messages asynchronously.

Services written using this API are easy to understand and maintain, and services can send and receive any AVP combination permitted by the specification.

Sending and receiving non-standard AVPs and messages

Many Diameter specifications allow arbitrary AVPs to be added to messages and grouped AVPs. These are indicated in the specification by the following line in the definition of that message or grouped AVP:

* [AVP]

These are known as "extension AVPs" in the Diameter resource adaptors. The resource adaptors can be configured to handle arbitrary AVP definitions, and all resource adaptor types provide methods to set and get these extension AVPs.

The Diameter Base Resource Adaptor Type API also provides methods to construct and send a Diameter message with an arbitrary command code and vendor ID.

What’s in the Diameter Resource Adaptors Package?

The Diameter Resource Adaptors Package includes:

  • Resource adaptors and corresponding resource adaptor types for Diameter CCA, Diameter Ro, Diameter Rf, Diameter Sh, Diameter Gx, and Diameter Base (which covers Diameter Base Accounting as well as supporting custom Diameter applications). For each resource adaptor type there is a component JAR file to compile services against and a deployable unit JAR for deployment. Resource adaptors only need the deployable unit JARs.

  • Simulator tools with very basic functionality to respond to incoming Diameter requests.

  • Example services with Ant scripts for building and deploying them.

  • Other deployable units that are shared by all Diameter resource adaptors: Diameter profile specification, Diameter base types library, Netty library, Google Guava library.

Deploying the Diameter Resource Adaptors

Warning From Diameter 2.6.0 onwards, the resource adaptors must be deployed in a Rhino SLEE running Java 7. They cannot be deployed on Java 6.

Deployment steps

The Diameter resource adaptors do not come with deployment scripts. Instead, each example service includes a script that installs and configures the applicable resource adaptor for that example. Developers and administrators should refer to the example scripts for the exact steps, and write their own script; but the basic procedure is as follows:

  1. Deploy the Diameter base types library that contains the Java types used by all Diameter resource adaptors.

  2. Deploy the Diameter profile specs.

  3. Deploy the Netty library shared by all Diameter resource adaptors (and some others).

  4. Deploy a Diameter resource adaptor type.

  5. Deploy a Diameter resource adaptor.

  6. Create a Diameter configuration profile (and profile table).

  7. Create a Diameter resource adaptor entity.

Configuring Diameter Resource Adaptors

You configure Diameter resource adaptors using:

Note
For details, see:

Diameter RA Configuration Properties

Below are common configuration properties that all Diameter resource adaptors use, followed by properties specific to:

Configuration properties for transport security (TLS) and more information about configuring TLS can be found on Configuring Diameter Transport Security.

The Diameter resource adaptors support active reconfiguration. This means that (most) configuration properties can be updated without deactivating and re-activating the resource adaptor entity. If a property cannot be updated at runtime, then an alarm is raised indicating that the entity must be deactivated and re-activated. The tables below indicate which properties allow active reconfiguration.

For profile-based configuration, some of the attributes can be changed while active. See Configuration Profiles for details. The profile is polled for changes according to the value of ConfigurationProfilePollTime. (This is disabled by default.)

Common configuration properties

Property What it specifies Values Default Active reconfig?

ConfigurationProfile

Diameter Configuration Profile from which to load the Diameter stack configuration

valid profile name specified as TableName/ProfileName

No

ConfigurationProfilePollTime

time between polling for changes to ConfigurationProfile, in milliseconds

1000 or greater; 0 to disable

0

Yes

ExtensionAvpSet

Diameter Extension AVP Set profile for configuring extension AVPs (if specified)

profile name specified as TableName/ProfileName

Yes

ExtensionAvpSetPollTime

time between polling for changes to ExtensionAvpSet in milliseconds

1000 or greater; 0 to disable

0

Yes

ConnectTimeout

timeout for waiting for outgoing transport connection establishment

number of milliseconds

30000

Yes

RequestTimeout

timeout for waiting for responses before firing a Timeout event

number of milliseconds

30000

Yes

WatchdogTimeout

timeout for waiting for watchdog responses (RFC3539 timer Tw)

number of milliseconds

30000

Yes

ReconnectDelay

delay before reconnecting (RFC6733 timer Tc)

number of milliseconds

30000

Yes

ForceReconnectAfterDPR

if true, always attempt to reconnect even if the server sent a DPR with Disconnect-Cause set to DO_NOT_WANT_TO_TALK_TO_YOU

true, false

false

Yes

FireToServiceID

service to fire events to (if specified)

Service ID as full display string as shown by management commands

Yes

ThreadPoolSize

size of thread pool for decoding incoming diameter messages

-1 = disable thread pool and use IO threads;
0 = use value of Runtime.getRuntime().availableProcessors()

0

No

WorkQueueSize

size of the task queue of thread pool for decoding incoming diameter messages

0 = use ThreadPoolSize * 1000

0

No

IOServerWorkers

number of IO threads serving incoming connections

0 = use value of Runtime.getRuntime().availableProcessors()

0

No

IOClientWorkers

number of IO threads serving outgoing connections

0 = use value of Runtime.getRuntime().availableProcessors()

0

No

SupportedVendorIds

a set of Supported-Vendor-Id AVP values used in CER and CEA, multiple comma separated values can be specified

integer number (from 0 to 2^32 inclusive); comma separated list of integer numbers

No

ExtendedTransportConfiguration

allows additional Netty settings to be supplied, for example those controlling the parameters of the pooled buffer allocator; these are not for general use and should be added only at the recommendation of OpenCloud engineers

valid list of extended properties

No

Quirks

comma separated list of strings enabling non-standard behaviour; these are not for general use and should be added only at the recommendation of OpenCloud engineers

valid list of supported Quirks

No

Diameter Base configuration properties

Diameter Base also uses this configuration property:

Property What it specifies Values Default Active reconfig?

VendorSpecificApplicationId

value to put into the Vendor-Specific-Application-Id AVP in CER/CEA and CUR/CUA messages

grouped AVP containing a Vendor-Id field and a Auth-Application-Id field — must contain both values in the format Vendor-Id:Auth-Application-Id

Yes

Active reconfiguration of this property automatically triggers sending CUR message to all active peers supporting RFC6737.

Diameter Accounting/Rf configuration properties

Diameter Base Accounting and Diameter Rf also use these configuration properties:

Property What it specifies Active reconfig?

StatefulSessionTimeout

value for Ts as defined by section 8.2 of RFC 6733 — the timeout value for stateful accounting sessions

Yes

AcctInterimInterval

value to include (if specified) in an Acct-Interim-Interval AVP for Accounting-Answer, when starting a session

Yes

Diameter 3GPP configuration properties

Diameter resource adaptors that implement a 3GPP reference point (Ro, Rf, Gx, and Sh) also use this configuration property.

Property What it specifies Values Active reconfig?

3GPPVersion

3GPP version of protocol supported by the resource adaptor

two forms allowed:

  • in the form of Vxyz, where xyz is three-character version number used in names of 3GPP specifications; for example, V710 for V7.1.0 or Va00 for V10.0.0. The value is case-sensitive: the V must be uppercase and other letters lowercase.

  • in the decimal form x.y.z; for example, 7.1.0 for V7.1.0 or 10.0.0 for V10.0.0. There is no V letter, only the decimal version number.

Note Prior to Diameter 2.6.0 this value was optional and a "default" version would be used. From 2.6.0 onwards a value must be supplied or the resource adaptor will not activate. See additional notes below.

No

3GPP version

Your SBB must use the provider factory method and the types sub-package that matches the value you specify. For example, for Ro V10.0.0 (3GPPVersion=Va00) or (3GPPVersion=10.0.0), you would use the provider method

RoProviderFactory.getRoProviderVa00()

and import your Diameter types from the package

org.jainslee.resources.diameter.ro.types.va00
Note
See also
Diameter Resource Adaptor Statement of Compliance and Javadoc for a list of supported specification versions for each resource adaptor.

Diameter CCA/Ro/Gx configuration properties

Diameter CCA, Diameter Ro, and Diameter Gx also use these configuration properties.

Property What it specifies Values Default Active reconfig?

ServiceContextId

value to put into the Service-Context-ID AVP for all messages

string value specified as "service-context" "@" "domain" (see RFC 4006 section 8.42)

diametercca
@opencloud.com

Yes

ExtensionMessages

if true, support both Diameter base and Diameter application specific sessions (CCA, Ro, Gx); otherwise allow only processing of messages that are explicitly used within Diameter application (as specified by corresponding RFC and 3GPP specifications for CCA, Ro, Gx)

true, false

false

Yes

ReplicateActivities

enable credit control session state replication, so that dialog activities can continue on other cluster nodes after a node failure; if true, replication is enabled; requires a clustered production Rhino installation

true, false

false

No

TxTimeout

timeout for waiting for responses before firing a RequestTxTimeout event (RFC4006 Tx Timer); session state after timeout depends on Credit-Control-Failure-Handling AVP or Direct-Debiting-Failure-Handling AVP (RFC4006 section 5.7 and section 6.5 respectively)

number of milliseconds; 100 or greater

10000

Yes

ValidityTimeBasedTccTimeout

Controls Tcc session supervision timer driven behaviour (RFC 4006 section 13 and section 7).
Supported values:

  • -1 = Tcc timer disabled

  • 0 = Tcc timer initialized to 2 x Validity-Time AVP seconds

  • >0 = provides a default Validity-Time AVP value. Whenever answer does not contain a Validity-Time AVP, that AVP is added by RA with value equal to defined ValidityTimeBasedTccTimeout. Processing continues exactly as in case of 0.

integer value -1, 0, >0

0

No

CCSessionFailover

provides a default value for CC-Session-Failover AVP for credit control server sessions created by RA (RFC4006 section 8.4); if configuration value is specified, it is automatically set in outgoing answers that do not already contain this AVP

optional string parameter; if provided, must be one of: FAILOVER_NOT_SUPPORTED, FAILOVER_SUPPORTED

Yes

CreditControlFailureHandling

provides a default value for Credit-Control-Failure-Handling AVP for credit control server sessions created by RA (RFC4006 section 8.14); if configuration value is specified, it is automatically set in outgoing answers that do not already contain this AVP

optional string parameter; if provided, must be one of: TERMINATE, CONTINUE, RETRY_AND_TERMINATE

Yes

DirectDebitingFailureHandling

provides a default value for Direct-Debiting-Failure-Handling AVP for credit control server sessions created by RA (RFC4006 section 8.15); if configuration value is specified, it is automatically set in outgoing answers that do not already contain this AVP

optional string parameter; if provided, must be one of: TERMINATE_OR_BUFFER, CONTINUE

Yes

InitialTerminateDuplicateHandling

switch the responsibility for handling of duplicated INITIAL and TERMINATION session credit-control requests (CCR with CC-Request-Type AVP equal to INITIAL_REQUEST or TERMINATION_REQUEST) between RA or service.
Supported values:

  • NO — RA upon receiving duplicated CCR with CC-Request-Type AVP equal to INITIAL_REQUEST or TERMINATION_REQUEST automatically generates an error response and terminates the session

  • SERVICE — RA does not handle duplicated session credit-control CCRs automatically, service is responsible for detecting and appropriately handling duplicates, service is also allowed to send duplicated CCRs.

Note Duplicated TERMINATION session credit-control requests are handled up to LingerOnTerminate milliseconds after CC session reaching Terminated state. For description of LingerOnTerminate see below.

string parameter; must be one of: NO, SERVICE

NO

Yes

LingerOnTerminate

delay ending diameter activity by LingerOnTerminate milliseconds after CC session reaching Terminated state; must be disabled (set to 0), if InitialTerminateDuplicateHandling is set to value NO

number of milliseconds; 1000 or greater; 0 to disable

0

Yes

SessionTimeout

session inactivity timeout used by RA when handling SLEE queryLiveness call; if an activity has been idle in the SLEE for a prolonged period of time it will be terminated, but not sooner than SessionTimeout ms from last processed message

number of milliseconds

600000

Yes

Diameter RA Configuration Profiles

The ConfigurationProfile configuration property provides the resource adaptor entity with the name of a SLEE profile to use.

The profile specification ID is name=Diameter Configuration, vendor=OpenCloud, version=2.6. The example build file demonstrates the SLEE management commands required to create a valid Diameter configuration profile and create a resource adaptor entity with the configuration property. (In practice, normally a profile export XML file is used.)

The profile is polled for changes according to the value of ConfigurationProfilePollTime in the resource adaptor configuration properties. (This is disabled by default).

Most attributes can be changed while the resource adaptor entity is active, but some cannot — as indicated in the tables below.

Host identity

Attribute What it specifies Active reconfig?

ProductVendorId

product name to use in Product-Name AVPs generated by the stack

Yes

Product

value to be used as Vendor-Id AVP in CER/CEA messages

default value is 19808, that is:
OpenCloud Ltd. SMI Network Management Private Enterprise Code

Yes

Version

version number to use in all Firmware-Revision AVPs generated by the stack

must be a positive int

Yes

Realm

realm to use in all Origin-Realm AVPs

No

Single-node or multi-node host configuration

Two sets of attributes can configure the Diameter host and listener settings. One set, for single-node Rhino instances (including the Rhino SDK), uses simple types. The other, for multi-node clusters, uses array types. The EnableMultiNodeConfig attribute tells the resource adaptor which to use.

Attributes used in both single-node and multi-node configuration.

Attribute What it specifies Active reconfig?

EnableMultiNodeConfig

whether to use NodeIDs, PerNodeHosts, PerNodeListenAddresses, and PerNodePorts to set up the hostnames and listen addresses of each node

Yes

AllowUnknownPeers

if true, then any peer may connect to this node;
otherwise peers connecting to this node as clients must be defined in the Peer Table

Yes
Warning Multi-node host configuration must be used when a Diameter resource adaptor is deployed in a multi-node Rhino cluster. This is so that each node has a unique identity (using the PerNodeHosts attribute). The OpenCloud Diameter simulators will not accept connections from multiple hosts with the same identity (as required by the specification).

Single-node host configuration

Attribute What it specifies Active reconfig?

Host

host to use in all Origin-Host AVPs;
must be resolvable

No

ListenAddress

local address to listen on

if not specified, no listener is started

this attribute determines whether the entity operates in client mode or server mode

Yes

SecondaryAddresses

extra addresses to bind SCTP server channels to (SCTP multi-homing)

multiple addresses may be separated by commas

Yes

Port

listen port

Yes

Transports

transport(s) to listen on

values can be tcp, sctp, or tcp,sctp

Yes

Multi-node host configuration

Attribute What it specifies Active reconfig?

NodeIDs

a list of Node IDs

each element must be unique

the index of a node in NodeIDs defines the index that will be used in the arrays below

for example, if NodeIDs[0] = 101 and PerNodeHosts[0] = "cca1.foo.com", then that hostname will be used on node 101

Yes

PerNodeHosts

host names, one per node, in the same order as NodeIDs

used for the Origin-Host AVP on each node

each hostname must be unique

No

PerNodeListenAddresses

listen address, one per node, in the same order as NodeIDs

used as the listen address on each node; may be null or empty, in which case no listeners will be started on any node

Yes

PerNodeSecondaryAddresses

extra addresses, one element per node, in the same order as NodeIDs

used to bind SCTP server channels (SCTP multi-homing)

in each element, multiple addresses may be separated by commas

Yes

PerNodePorts

Diameter ports, one per node, in the same order as NodeIDs

used for the listen port on each node

ignored if PerNodeListenAddresses is null or empty

Yes
Note The Transports attribute cannot be specified per-node; the same value is used for all nodes.

Peer and realm configuration

There are two options for configuring a remote peer and realm. The simple peer configuration uses a handful of profile attributes to configure the essential information and sets all other values to defaults. The complex peer configuration uses two profile attributes that contain XML documents describing multiple peers and realms.

If the PeerTable and RealmTable attributes are set, then they will be used and all the attributes listed for simple peer and realm configuration will be ignored. If PeerTable and RealmTable are not set, then the simple peer configuration will be used.

Warning Using PeerTable and RealmTable is strongly recommended — the attributes for simple peer configuration will be removed in the next major release of Diameter.

Simple peer and realm configuration

Attribute What it specifies Active reconfig?

PeerHost

host of remote Diameter peer

Yes

PeerPort

port of remote Diameter peer

Yes

PeerAddress

(optional) address to override PeerHost when resolving address for outgoing connections

must be a numeric IP address

if not specified, the host set in PeerHost must be resolvable

Yes

PeerConnectAtStartup

whether to connect to the remote peer at startup

must be true or false

Yes

UseTLS

whether to establish TLS secure session with peer defined in PeerHost

Yes

ValidDN

value required (exact string match) for owner-distinguished name with certificate from peer (required if defined)

example value: CN=diameterclient, OU=example, O=OpenCloud, L=wellington, ST=wellington, C=NZ

Yes

ApplicationId

Diameter Application ID

Yes

ApplicationVendorId

Vendor ID

must be 0 for IETF-specified applications, or an IANA-assigned private enterprise number

Yes

Action

must be LOCAL for this version of the RA

Yes

Advanced peer and realm configuration

Attribute What it specifies Active reconfig?

PeerTable

valid XML document for peer table configuration

Yes

RealmTable

valid XML document for realm table configuration

Yes

RequestRouter

select outgoing request routing algorithm

value must be one of: METRIC or WEIGHT

Yes
Note
See also
Configuring peer and realm tables.

Configuring peer and realm tables

The peer and realm tables are specified using XML. Below are DTDs and examples of the Diameter peer and realm tables, with notes on their usage.

Peer table

The Diameter peer table specifies statically configured peers. All outgoing connections to peers must be configured statically. Incoming connections are usually dynamic, but you must configure peers statically if using TLS, because you must supply a valid DN for the peer.

Below are the DTD and examples for client and server.

URIs

The <uri> element is used to configure a peer. For outgoing connections, this information is used to create the connection. For incoming connections, this information is used when allowUnknownPeers is set to false. If allowUnknownPeers is set to true, then peers do not need to be configured, unless they need to use TLS.

Using <uri> vs <hostname>, <port>, and <tls>

The use of <hostname>, <port> and <tls> is deprecated. The <uri> element contains exactly the same information, and it should be used instead.

The format for a URI is specified in RFC6733 section 4.3, Derived AVP Data Formats.

The equivalent setting for the old <tls> option is determined by the protocol specifier, aaa or aaas. It is critical that the correct protocol is used for both outgoing peer connections and configured peers for incoming connections.

For incoming connections, the port is ignored and to avoid confusion it should not be specified.

Transports

There are two transports supported, TCP and SCTP. To use SCTP, the URI should have a suffix of ;transport=sctp. If no suffix is specified, TCP is used; but ;transport=tcp can still be used for clarity.

For incoming connections, the transport is ignored, but can be set as a hint to a reader of the configuration. The actual transports supported for incoming connections are specified by the transports profile attribute in the configuration profile.

URI examples
aaa://host.example.com

This configures a peer with host name host.example.com. For outgoing connections it will use the default port (3868, the default port when TLS is not used), TCP, and no TLS.

aaa://host.example.com:6666;transport=sctp

This configures a peer with host name host.example.com. For outgoing connections it will use port 6666, SCTP, and no TLS.

aaas://host.example.com:6668;transport=tcp

This configures a peer with host name host.example.com. For outgoing connections it will use port 6668, TCP, and no TLS. If an incoming connection is received from this peer the stack will attempt a TLS handshake. The listen port will not be 6666 but will be whatever is configured in the ListenPort configuration property (link). A <valid-dn> setting must also be supplied.

Warning TLS over SCTP is not supported.

Peer Connection Options

Options can be specified to control low-level TCP or SCTP settings for a peer connection. These can be specified for individual outgoing connections (<option> elements within a <peer>), all outgoing connections (<default-options> element within a <peer-table>) and all incoming connections (<server-default-options> element within a <peer-table>).

The supported options are TCP_NODELAY and SCTP_NODELAY.

The other options defined by the ChannelOption Netty class (and SctpChannelOption for additional SCTP options) are available, however these have not been certified for use by OpenCloud and you should contact your OpenCloud account management team should you require support for these.

Note that only options whose type is either a Java primitive type, InetSocketAddress, or com.sun.nio.sctp.SctpStandardSocketOptions.InitMaxStreams can be set. The Java type of the option must be specified in the <option-type> element, for example java.lang.Boolean or java.net.InetSocketAddress.

Value format for options with type com.sun.nio.sctp.SctpStandardSocketOptions.InitMaxStreams (that is the SCTP_INIT_MAXSTREAMS option) is maxInStreams,maxOutStreams where both maxInStreams and maxOutStreams are integers between 0 and 65536 inclusive. Note that in this version of Diameter Resource Adaptor the SCTP_INIT_MAXSTREAMS is applied only to outgoing connections.

Peer table DTD

Peer table configuration must conform to this DTD.

<?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 may be empty initially, if this is a Diameter server only -->
<!ELEMENT peer-table ( server-child-options?, default-options?, peer* )>
<!ATTLIST peer-table allowUnknownPeers (true|false) "false">

<!ELEMENT server-child-options ( option* )>
<!ELEMENT default-options ( option* )>

<!-- Peer's port and tls only required if connectAtStartup=true -->
<!ELEMENT peer ( uri?, hostname?, port?, address?, tls?, valid-dn?, host-ip-address*, option* )>
<!ATTLIST peer connectAtStartup (true|false) "false">

<!-- Specify peer address as a DiameterURI. If specified then hostname, port and tls will be ignored Using a URI is the only way to specify that sctp transport should be used. The connect address can still be optionally overridden using the address element. -->
<!ELEMENT uri (#PCDATA)>

<!-- Optionally override the address to connect to (defaults to host from uri or hostname). This should not be specified if the uri (or hostname) contains a host that can be successfully resolved to an IP address. -->
<!ELEMENT address (#PCDATA)>

<!-- Specify peer address details separately. This is deprecated, uri should be used instead. -->
<!ELEMENT hostname (#PCDATA)>  <!-- Deprecated, use uri instead. -->
<!ELEMENT port (#PCDATA)>      <!-- Deprecated, use uri instead. -->
<!ELEMENT tls (#PCDATA)>       <!-- Deprecated, use uri instead. -->

<!ELEMENT valid-dn (#PCDATA)>

<!-- Can be used override the default behaviour of adding a Host-IP-Address AVP for every IP address to the CER -->
<!ELEMENT host-ip-address (#PCDATA)>

<!ELEMENT option (option-name, option-type, option-value?)>
<!ELEMENT option-name (#PCDATA)>
<!ELEMENT option-type (#PCDATA)>
<!ELEMENT option-value (#PCDATA)>

Peer table client examples

TCP connections with default options.

<?xml version="1.0" encoding="UTF-8"?>
<!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>
    <default-options>
        <option>
            <option-name>TCP_NODELAY</option-name>
            <option-type>java.lang.Boolean</option-type>
            <option-value>true</option-value>
        </option>
    </default-options>
    <peer connectAtStartup="true">
        <uri>aaa://diameterserver:3868;transport=tcp</uri>
        <address>127.0.0.1</address>
        <valid-dn>CN=diameterserver,OU=example,O=OpenCloud,L=wellington,ST=wellington,C=NZ</valid-dn>
    </peer>
    <peer connectAtStartup="true">
        <uri>aaas://diameterserver2:5868;transport=tcp</uri>
        <address>127.0.0.1</address>
        <valid-dn>CN=diameterserver,OU=example,O=OpenCloud,L=wellington,ST=wellington,C=NZ</valid-dn>
    </peer>
</peer-table>

SCTP connections without default options.

<?xml version="1.0" encoding="UTF-8"?>
<!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>
    <peer connectAtStartup="true">
        <uri>aaa://diameterserver:3868;transport=sctp</uri>
        <address>127.0.0.1</address>  <!-- Used if "diameterserver" is a logical name that does not resolve to an address, useful for testing. -->
    </peer>
    <peer connectAtStartup="true">
        <uri>aaa://ocs-server:3868;transport=sctp</uri>
        <!-- No address element should be used if "ocs-server" is resolvable. -->
        <option>
            <option-name>SCTP_NODELAY</option-name>
            <option-type>java.lang.Boolean</option-type>
            <option-value>false</option-value>
        </option>
    </peer>
</peer-table>

Peer table server example (with TLS)

<?xml version="1.0" encoding="ISO-8859-1"?>

<!DOCTYPE peer-table PUBLIC "-//Open Cloud Ltd.//DTD Diameter Peer Table Configuration 1.0.1//EN" "http://www.opencloud.com/dtd/diameter-peer-table-1.0.1.dtd">

<peer-table allowUnknownPeers="false">
    <!-- 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. Since valid DNs must be supplied for incoming TLS connections, it is logical for allowUnknownPeers to be false when using TLS. -->
    <peer>
        <uri>aaas://diameter1.opencloud.com</uri> <!-- Will accept connections from this peer -->
        <valid-dn>CN=diameterclient,OU=example,O=OpenCloud,L=wellington,ST=wellington,C=NZ</valid-dn>
    </peer>
</peer-table>

Peer table server example (with server socket options)

An empty peer table (with allowUnknownPeers="true") can be used to specify channel options that will be set on incoming sockets (children of the acceptor sockets).

<?xml version="1.0" encoding="UTF-8"?>
<!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">
    <server-child-options>
        <!-- Both options can be specified because they will be filtered according to transport of incoming connections. -->
        <option>
            <option-name>TCP_NODELAY</option-name>
            <option-type>java.lang.Boolean</option-type>
            <option-value>true</option-value>
        </option>
        <option>
            <option-name>SCTP_NODELAY</option-name>
            <option-type>java.lang.Boolean</option-type>
            <option-value>true</option-value>
        </option>
    </server-child-options>
</peer-table>

Realm table

This Diameter realm table specifies the routing for the Diameter router. Below are the DTD and an examples.

Realm table DTD

Realm table configuration must conform to this DTD.

<?xml version="1.0" encoding="ISO-8859-1"?>
<!-- <!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"> -->

<!ELEMENT realm-table ( realm*, default-route? )>
<!ELEMENT realm ( realm-name, extension-property*, application-route+ )>
<!ELEMENT realm-name (#PCDATA)>

<!-- The extension-property element defines an extension property that is used to provide additional RA type specific configuration. The element contains an optional description of the extension property, its name, Java type and value. -->
<!ELEMENT extension-property (description?, extension-property-name, extension-property-type, extension-property-value)>

<!-- The description element may contain any descriptive text about the parent element. -->
<!ELEMENT description (#PCDATA)>

<!-- The extension-property-name element contains the name of extension property. Example: <extension-property-name>CreditControlFailureHandling</extension-property-name> -->
<!ELEMENT extension-property-name (#PCDATA)>

<!-- The extension-property-type element contains a fully-qualified Java class name of an extension property. The following are the legal values of extension-property-type: java.lang.Boolean, java.lang.String, java.lang.Character, java.lang.Integer, java.lang.Double, java.lang.Byte, java.lang.Short, java.lang.Long, and java.lang.Float. Example: <extension-property-type>java.lang.String</extension-property-type> -->
<!ELEMENT extension-property-type (#PCDATA)>

<!-- The extension-property-value element contains the value of an extension property. The value must be a string that is valid for the constructor of the configuration property's declared type that takes a single java.lang.String parameter, or for java.lang.Character configuration properties, a single character. Example: <extension-property-value>CONTINUE</extension-property-value> -->
<!ELEMENT extension-property-value (#PCDATA)>



<!ELEMENT application-route ( application, action, transport-failover?, peer-ref+ )>

<!ELEMENT application ( application-id, vendor-id? )>
<!ELEMENT application-id (#PCDATA)>
<!ELEMENT vendor-id (#PCDATA)>

<!-- Must be LOCAL, other actions (RELAY, PROXY, REDIRECT) are not supported yet. -->
<!ELEMENT action (#PCDATA)>

<!-- The transport-failover element selects the expected behaviour in case of transport failure. If request could be routed to multiple peers (e.g. multiple peer-ref(s) specified for application-route or default-route) and the selected peer fails, transport-failover element value defines if request is sent to next peer or a failure is reported to SBB. Must be one of BEFORE_FIRST_SEND, RETRANSMIT_ONLY_FIRST, ALWAYS, default is BEFORE_FIRST_SEND. BEFORE_FIRST_SEND - select next peer only when request is the first request in a session and failure occurred before message was put on the wire. RETRANSMIT_ONLY_FIRST - in addition to BEFORE_FIRST_SEND behaviour, select next peer when the first request in a session timeouts (retransmit to next peer) ALWAYS - in addition to RETRANSMIT_ONLY_FIRST behaviour, select next peer for any (first, subsequent) request in a session (including retransmission of request) Note: ALWAYS implicitly requires that session state is replicated by peers acting as servers in destination realm (or that session state does not require replication). -->
<!ELEMENT transport-failover (#PCDATA)>

<!-- Refers to a peer in the peer table -->
<!ELEMENT peer-ref ( hostname, metric? )>
<!ELEMENT hostname (#PCDATA)>
<!-- Routing metric, defaults to 0. Higher numbers indicate higher priority -->
<!ELEMENT metric (#PCDATA)>

<!-- If all else fails, look here for a peer to use. -->
<!ELEMENT default-route ( transport-failover?, peer-ref+ )>

Realm table example

<?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>test</realm-name>
       <application-route>
           <application>
               <application-id>4</application-id>
               <vendor-id>0</vendor-id> <!-- optional, default is zero -->
           </application>
           <action>LOCAL</action>
           <peer-ref>
               <hostname>diameterserver</hostname>
               <metric>1</metric>
           </peer-ref>
       </application-route>
    </realm>
    <default-route>
       <peer-ref>
           <hostname>diameterserver</hostname>
           <metric>1</metric>
       </peer-ref>
    </default-route>
</realm-table>

Configuring Diameter Transport Security

To enable TLS for Diameter peer connections, you must use configuration properties to specify a certificate key store, certificate key store password, trust key store, and trust key store password.

TLS Configuration Properties

Property What it specifies Values Default

CertificateKeyStore

file to load certificate key store from

filename on the local file system, or URL

Note

May contain system properties in Ant style, for example ${rhino.dir.home} to refer to the Rhino home directory.

By default, the resource adaptors have permission to read files from ${rhino.dir.home}/keystores.

CertificateKeyStorePassword

password for certificate key store

any string

TrustKeyStore

file to load trust key store from

filename on the local file system, or URL

Note

May contain system properties in Ant style, for example ${rhino.dir.home} to refer to the Rhino home directory.

By default, the resource adaptors have permission to read files from ${rhino.dir.home}/keystores.

TrustKeyStorePassword

password for trust key store

any string

CipherSuites

comma-separated list of TLS cipher suites to be enabled for use when establishing TLS handshake

any values supported by virtual machine vendor;
if empty, uses default cipher suites

SSLSessionTimeout

time after which TLS session should be invalidated and new session will be established
(cipher keys change)

number of seconds;
0 = sessions do not time out

0

AllowTLSDowngradeToRFC3588

is downgrade to TLS support in accordance with RFC 3588 allowed.

if true allow secure connections to use TLS as specified in either RFC 6733 or RFC 3588;
if false require secure connections to use TLS as specified in RFC 6733

Note

If set to true affects behaviour controlled by ConnectTimeout property.

Half of time allotted by ConnectTimeout is used as time limit for establishing a TLS secure connection as specified in RFC 6733. If that attempt fails the remaining time is used to retry a connection using TLS as specified in RFC 3588.

false

Key stores

For information about creating a key store, please see the Java Virtual Machine vendor documentation: Sun/Oracle keytool documentation and Sun/Oracle general information about TLS support in the JSSE Reference Guide.

Peer configuration

To use TLS as a client: configure the key stores as above; and enable TLS, either with a aaas:// URI in the PeerTable XML configuration, or the UseTLS attribute in the simple peer table configuration.

When the Diameter resource adaptor is acting as server, incoming connections must be from peers listed in the peer table; they cannot be added dynamically when they connect (as non-secure peers can). Even if allowUnknownPeers is set to true and the client tries to initiate TLS on a connection, the server will treat the connection as not using TLS.

Configuring Extension AVPs

Diameter resource adaptors can specify extension (custom) AVPs, using the Diameter Extension AVP and Diameter Extension AVP Set SLEE profile specifications.

When a resource adaptor entity is configured to support a particular set of extension AVPs, the AVP definitions will be loaded when the entity starts. The Diameter stack can then use these definitions to encode AVPs that are added to messages or grouped AVPs, and decode AVPs that are received.

Diameter Extension AVP

Note Profile Specification ID: name=Diameter Extension AVP,vendor=OpenCloud,version=2.5

Profiles of this type are used to specify the values for a single extension AVP.

Attribute What it specifies What it’s used for

AvpCode

code for this AVP

to look up this extension AVP definition

AvpName

AVP name

(not used — for reference only)

AvpType

AVP type

by the stack to encode and decode the AVP

MandatoryRule

Mandatory Rule setting for this AVP

Valid values are defined by the FLAG_RULE constants in DiameterAvp

ProtectedRule

Protected Rule setting for this AVP

Valid values are defined by the FLAG_RULE constants in DiameterAvp

VendorId

vendor ID code for this AVP

to look up this extension AVP definition

Diameter Extension AVP Set

Note Profile Specification ID: name=Diameter Extension AVP Set,vendor=OpenCloud,version=2.5

Profiles of this type are used to specify a list of Diameter Extension AVP profile names. The resource adaptor entity configuration property ExtensionAvpSetProfileId must reference a profile of this type.

Attribute What it specifies

ExtensionAvps

array of Diameter Extension AVP profile names, in ProfileTableName/ProfileName format.

Diameter RA Request Routing Configuration

A request is sent towards its final destination using a combination of the Destination-Realm and Destination-Host AVPs. There are three specification-mandated combinations of these AVPs.

Specification-mandated AVP combinations

  • Diameter transport layer messages (such as CER) MUST NOT contain either Destination-Realm or Destination-Host AVPs.

  • A directly addressed request, that is a request that needs to be sent to a specific peer among those serving a given realm, MUST contain both the Destination-Realm and Destination-Host AVPs.

  • A realm-addressed request, that is a request that needs to be sent to ANY single peer serving a specific realm, MUST contain a Destination-Realm AVP, but MUST NOT contain a Destination-Host AVP.

Of these three addressing methods, only the realm addressing requires additional configuration to select a routing algorithm that will be used by Diameter RAs. Routing and failover behaviour specific to this addressing mode is described in following sections:

General outgoing request routing

Requests addressed to a specific Diameter peer (both Destination-Host and Destination-Realm defined) are routed to that specific peer. Routing of realm-addressed requests requires additional configuration and includes route selection made by the RA, for the first request in a session. Subsequent requests in the same session are directed to the same peer. If the previously selected peer fails, session failover may take place; and the session might continue with requests directed to another peer in the same realm.

The configuration and general behaviour of Diameter RAs for outgoing request routing is based on the user-provided realm table.

The realm table may specify multiple realms and a default route:

<realm-table>
    <realm>
       <realm-name>opencloud</realm-name>
       <application-route>
           ...
       </application-route>
    </realm>
    <default-route>
       ...
    </default-route>
</realm-table>

Default Route

When routing the first outgoing request in a Diameter session, the realm table is searched for a realm definition matching the request`s Destination-Realm AVP value. If a matching realm is not found, then the default route is used.

If the default route is defined, it must contain one or more peer references:

<default-route>
   <peer-ref>
       <hostname>diameterserver1</hostname>
       <metric>1</metric>
   </peer-ref>
   <peer-ref>
       <hostname>diameterserver2</hostname>
       <metric>2</metric>
   </peer-ref>
</default-route>

If there is only a single peer reference defined, or only a single peer is currently reachable (a network connection is established), the request is routed to that peer. Whenever there are multiple peers configured and reachable, a specific request routing algorithm is invoked to select among available peers.

Realm

When routing the first outgoing request in a Diameter session, and the realm table contains configuration for a realm matching the request`s Destination-Realm AVP value, that configuration is used as input to the user-selected routing algorithm.

The realm must contain at least one application route with one or more peer references:

<realm>
   <realm-name>opencloud</realm-name>
   <application-route>
       <application>
           <application-id>4</application-id>
           <vendor-id>0</vendor-id> <!-- optional, default is zero -->
       </application>
       <action>LOCAL</action>
       <transport-failover>ALWAYS</transport-failover>
       <peer-ref>
           <hostname>diameterserver1</hostname>
           <metric>1</metric>
       </peer-ref>
       <peer-ref>
           <hostname>diameterserver2</hostname>
           <metric>2</metric>
       </peer-ref>
   </application-route>
</realm>

The application route to use is selected based on the Vendor-Specific-Application-Id, Auth-Application-Id, or Acct-Application-Id AVP value in the request. If a matching application route is not found, then the default route is used. If there is only a single peer reference defined, or only a single peer is currently reachable (a network connection is established), the request is routed to that peer. Whenever there are multiple peers configured and reachable, a specific request routing algorithm is invoked to select among available peers.

Transport failover of Diameter sessions

This section describes Diameter RA behaviour when a connected peer fails.

When routing the first request on a new Diameter session, a failed peer is treated the same as if it was never connected. Diameter RAs provide an additional realm table configuration element, transport-failover, to select the expected RA behaviour when routing subsequent requests on a Diameter session. If a request could be routed to multiple peers (for example, if multiple peer-refs are specified for application-route or default-route) and the selected peer fails, then the transport-failover element value defines whether the request is sent to a different peer or a failure is reported to SBB.

The following values are supported by the transport-failover configuration element:

Value What it specifies 
BEFORE_FIRST_SEND

Select the next peer only when: the request is the first request in a session; and a failure occurred before the message was put on the wire.

(this is the default value)

 
RETRANSMIT_ONLY_FIRST

In addition to BEFORE_FIRST_SEND behaviour, select the next peer when the first request in a session times out (retransmit to the next peer).

 
ALWAYS

As well as the RETRANSMIT_ONLY_FIRST behaviour, select the next peer for any (first or subsequent) request in a session (including retransmission of the request).

Note ALWAYS implicitly requires that the session state is replicated by peers acting as servers in the destination realm (or that the session state does not require replication).

Outgoing request routing algorithms

This version of the Diameter RAs supports two routing algorithms: METRIC and WEIGHT. Configuration syntax within the realm table is the same for both routing algorithms and is based on the metric value defined for the peer reference. The difference between them is how the metric value is interpreted:

  • METRIC — The metric value represents a "cost" of the route to the peer. The peer with the lowest cost (lowest metric value) is selected whenever reachable. If the metric of all peer references is equal, routing is done in a round-robin fashion. Peers with the same metric value are ordered based on the configuration order (the peer reference specified first is preferred to a peer reference specified later).

  • WEIGHT — The metric value assigns a performance weight to each peer. Peers with a higher weight value receive a larger percentage of requests. The metric values of all peers in the route are summarized: the percentage of requests directed to a peer is equal to the peer’s metric value divided by the sum of metric values of all peers in the route. For example, for a route with three peers: peer A metric 10, peer B metric 15, and peer C metric 25, the percentage of initial requests that will be directed to each peer is: peer A 20%, peer B 30%, peer C 50%. When the metrics of all peer references are equal, the behaviour is equivalent to a round-robin algorithm.

Selection between routing algorithms is made using the RequestRouter attribute of the Diameter Configuration Profile.

Client Mode and Server Mode

Diameter resource adaptor entities operate in one of two modes: client or server. The presence of ListenAddress attribute in the configuration profile determines the mode.

If ListenAddress is specified, the entity will operate in server mode, otherwise it will operate in client mode. Depending on the mode, only a subset of requests will be accepted.

Requests accepted by particular Diameter resource adaptor for a given mode:

Cca, Ro, Gx Base (Accounting), Rf Sh

Client mode

ReAuthRequest AbortSessionRequest

requests for which session already exists

PushNotificationRequest

Server mode

all requests

all requests

UserDataRequest ProfileUpdateRequest SubscribeNotificationsRequest

Diameter Credit-Control Fault Tolerance

Diameter RAs (Diameter CCA, Ro, and Gx) using credit-control sessions (RFC 4006) support a fault-tolerant mode. In this mode, session state is replicated among nodes in the cluster.

This RA operating mode, paired with a service designed and configured to be replicated, allows service instances and credit-control sessions to continue uninterrupted operation — even if a cluster node fails or network segmentation occurs.

Below are details of configuration and behaviour related to failures for both server and client credit-control sessions; including credit-control functionality that affects: outgoing request routing, request re-transmissions (AVPs controlling failure procedures), and session termination (Tx and Tcc timers).

Credit-control session replication and adoption

For credit-control sessions used by the Diameter CCA, Ro, and Gx resource adaptors, session replication is enabled using the ReplicateActivities RA configuration property.

When session replication is enabled, credit-control session state is stored in the Rhino Replicated Storage facility. If one of the nodes within a cluster fails after any hardware, software, or network error, credit-control sessions served by the failing node are "adopted" by another node within the cluster.

AVPs controlling session adoption

Credit-control sessions use additional AVPs to control request re-transmissions and failover behaviour. Credit-control sessions store and expose current values of these AVPs to services. Initial values are based on RA configuration, and are later updated based on messages exchanged in the session.

Here are the RFC 4006 AVPs for controlling failure:

AVP What it’s for

CC-Session-Failover

Tells whether moving the credit-control message stream to a backup server during an ongoing credit-control session is supported.

Credit-Control-Failure-Handling

Used during session-based credit-control. The credit-control client uses information in this AVP to decide what to do if sending credit-control messages to the credit-control server has been, for instance, temporarily prevented due to a network problem.

Direct-Debiting-Failure-Handling

Used during one-time event credit-control (Requested-Action AVP set to DIRECT_DEBITING). The credit-control client uses information in this AVP to decide what to do, for example if sending credit-control messages to the credit-control server has been, for instance, temporarily prevented due to a network problem.

Session adoption of credit-control sessions is based on the CC-Session-Failover AVP value and session type (client or server):

  • If CC-Session-Failover is equal to FAILOVER_SUPPORTED, the session is always adopted.

  • If CC-Session-Failover is NOT equal to FAILOVER_SUPPORTED:

    • Server sessions are not adopted (that is, they are terminated).

    • Client session are only adopted if there is only a single peer where subsequent requests can be routed. That is, either the destination host for the session is defined, or realm addressing is used and there is only a single peer in the realm or default route configured.

Configuring failure and failover AVPs

The initial values of CC-Session-Failover, Credit-Control-Failure-Handling, and Direct-Debiting-Failure-Handling for each credit-control session come from user-provided defaults. For server sessions, those values are configured using Diameter RA Configuration Properties. Client-side configuration of failure and failover related AVPs is done per realm. The diameter realm DTD version 1.1 defines an additional element extension-property that can be specified for the realm. For example:

<realm>
    <realm-name>opencloud</realm-name>
    <extension-property>
        <extension-property-name>CCSessionFailover</extension-property-name>
        <extension-property-type>java.lang.String</extension-property-type>
        <extension-property-value>FAILOVER_NOT_SUPPORTED</extension-property-value>
    </extension-property>
    <extension-property>
        ...
    </extension-property>
    <application-route>
        ...
    </application-route>
</realm>

Diameter CCA, Ro, and Gx resource adaptors interrogate realm configuration in search of the following extension properties:

Extension property Values Default

CCSessionFailover

optional string parameter

If provided must, be one of:

  • FAILOVER_NOT_SUPPORTED

  • FAILOVER_SUPPORTED

FAILOVER_SUPPORTED if application-route with application id equal to 4 has a transport-failover element with value ALWAYS

(otherwise FAILOVER_NOT_SUPPORTED or undefined, which is equivalent)

CreditControlFailureHandling

optional string parameter

If provided must, be one of:

  • TERMINATE

  • CONTINUE

  • RETRY_AND_TERMINATE

DirectDebitingFailureHandling

optional string parameter

If provided must, be one of:

  • TERMINATE_OR_BUFFER

  • CONTINUE

Whenever a session has a specific failure or failover AVP value defined (possibly based on its configuration or a previously received credit-control answer), the RA will add those AVPs to its outgoing credit-control answers (if those answers do not already contain such an AVP).

On the other hand, if a credit-control answer contains a value for a failure or failover AVP, that value is used to update the session-stored value.

Warning Session failure and failover AVP values are initialized to configuration-defined values ONLY if the destination realm is known when creating the session. That is, the session must be created by a call to the RA provider createClientSessionActivity method, with a non-null destination realm parameter value.

Session adoption state changes

Session adoption is supported for sessions in specific states. Session state itself may be changed due to session adoption.

The following table describes credit-control state and session adoption interdependence:

Credit-control
session state		 Adoption
allowed?		 State
after adoption		 
Idle

No

 
Terminated
 
Open

Yes

 
Open
 
PendingEvent

No

 
Terminated
 
PendingInitial

No

 
Terminated
 
PendingUpdate

Yes

 
Open
 
PendingTerminate

Yes

 
Open
 
Terminated

No

 
Terminated

Credit-control session-specific timers

Credit-control specification RFC4006 defines additional timers, Tx and Tcc, used for both client and server credit-control sessions.

Tx timer

The Tx timer is introduced to control the waiting time for clients in Pending states. When the Tx timer elapses, the credit-control client takes action towards the end user based on the value of the Credit-Control-Failure-Handling or Direct-Debiting-Failure-Handling AVP.

The Tx timer is started when the session enters a PendingInitial, PendingUpdate, or PendingEvent state; that is, after sending any credit-control request other than a termination request.

Whenever a Tx timer expires before a credit-control answer is received, the RA fires a RequestTxTimeout event. A session might also be terminated based on the value of the Credit-Control-Failure-Handling or Direct-Debiting-Failure-Handling AVP.

Here are the states for Tx-timeout-related session termination:

Credit-control
session state		 Tx timeout
session terminated		 Note 
PendingEvent

when the request’s Requested-Action AVP is NOT DIRECT_DEBITING

The Direct-Debiting-Failure-Handling AVP value can change the expected behaviour of a service on a Tx timeout.

 
PendingInitial, PendingUpdate

when the session’s Credit-Control-Failure-Handling AVP value is TERMINATE

Other Credit-Control-Failure-Handling AVP values can change the expected behaviour of a service on a Tx timeout

Tcc timer

The Tcc timer supervises an ongoing server credit-control session. The Validity-Time AVP is used as input to set the Tcc timer value.

The Tcc timer is set to 2 times the Validity-Time AVP value present in the credit-control answer and/or the Validity-Time AVP defined in the Multiple-Services-Credit-Control AVP.

The Tcc timer is started when a successful credit-control answer is sent in the PendingInitial or PendingUpdate state, and stopped when a subsequent request is received. The Tcc timer expiry is reported to the service by firing a TccTimeout event; and the session is terminated.

Note Whenever Multiple-Services-Credit-Control AVPs are used for credit-control of multiple services in a single credit-control session, multiple Tcc timers are tracked. An incoming request with Multiple-Services-Credit-Control AVPs for a subset of services in use does not impact expiry time for the rest of the currently used services. Independently of how many services and Tcc timers are tracked, only a single TccTimeout event is fired.

Outgoing credit-control request routing

Credit-control sessions (as described in RFC 4006 section 5.7) impose additional routing rules for failure scenarios, on top of the algorithm and configuration described in Diameter RA Request Routing Configuration.

Note

Credit-control routing behaviour — influenced by the Tx Timer, CC-Session-Failover, and the Credit-Control-Failure-Handling AVP — is only applicable when using realm-based addressing.

Also, after evaluating the credit-control specific state, the actual re-transmission takes place only if the routing table configuration allows it; that is, if there is another peer available in the realm and the transport-failover configuration element value is appropriate.

One-time event routing

Routing of requests in the event of failures during one-time event credit-control is based on CC-Session-Failover. Re-transmission of a request to another peer is allowed when the session’s CC-Session-Failover value is FAILOVER_SUPPORTED.

Neither Tx timeout nor the Direct-Debiting-Failure-Handling AVP are relevant to RA-requested re-transmission. The Tx Timer and Direct-Debiting-Failure-Handling AVP do however impact expected service behaviour, as per RFC 4006 section 6.5.

Session-based credit control

Routing of requests in the event of failures during session-based credit control involves CC-Session-Failover, Tx Timer, and the session’s Credit-Control-Failure-Handling AVP value. Re-transmission to another peer in the realm is allowed when the session’s CC-Session-Failover value is FAILOVER_SUPPORTED.

Here are the re-transmission decisions in the event of transport failure; or answers with result codes DIAMETER_TOO_BUSY, DIAMETER_UNABLE_TO_DELIVER; or request timeout:

Credit-Control-Failure-Handling AVP Tx expired Tx not expired 
TERMINATE

report request timeout
(for INITIAL_REQUEST, UPDATE_REQUEST)

attempt re-transmission

 
CONTINUE, RETRY_AND_TERMINATE

attempt re-transmission

attempt re-transmission
Note As the Tx timer is not started for TERMINATION_REQUEST, re-transmission is always attempted.

Replicated credit-control service responsibilities

To provide a fault-tolerant service, both the RA and the deployed JAIN SLEE service must cooperate. This section describes what functionality is expected from a JAIN SLEE service to acheive a fault-tolerant solution when paired with a Diameter RA with session replication enabled.

At a high level, a Diameter RA operating with session replication enabled assures that: services that receive Diameter requests will continue to receive requests on the same session after a node failure (for the server); and services that send Diameter requests can continue to send requests on the same session after a node failure (for the client). This works through the RA replicating session state changes between cluster nodes, along with appropriate Diameter RA request-routing configuration.

The service is responsible for:

  • duplicate detection — The Diameter RA can be configured to allow service handling of duplicate requests. (E.g. if the service only supports mediation scenarios then it could forward the duplicates for handling by upstream server.)

  • handling failover for pending states — Such sessions are either terminated or their state is changed to OPEN during session adoption. Services are expected to:

    • use a guard timer and retry sending (for UPDATE_REQUEST or TERMINATION_REQUEST), or wait for re-transmission of the request from the client,

    • create a new session (for INITIAL_REQUEST).

  • using realm-based request addressing.

Tips and notes

Tip Below are general tips and notes about configuration and operation of the Rhino cluster, Diameter RA, and JAIN SLEE services with replication enabled.

Staging queue configuration

Rhino guards the state of replicated services and Diameter sessions using a distributed lock.

Warning

For the lock to be acquired on a node other than the node that previously owned the lock, one of two events must occur:

  • The node previously owning the lock must be informed and acknowledge the lock ownership change.

  • The node previously owning the lock must leave the primary component.

This is of little importance during normal operation, as Diameter sessions should be treated as sticky; and all messages in the same session should be handled by the same node (no lock ownership change). This is critical during a node-failure scenario. In that case, before a message for the session served by the failed node can be served on another node in the same cluster, the distributed locks guarding the service and Diameter session state must be acquired.

As the failed node is no longer there to acknowledge the lock ownership change, all Diameter message processing for sessions served by the failing node must wait until the failed node is no longer a part of primary component; that is, until node failure is detected and the node is considered dead.

The same is true when a node creates and tries to acquire a new lock, as this fact also must be acknowledged by other nodes in the primary component. Hence, in a failure scenario, acquisition of a new lock must wait for the failed node to leave the primary component.

During the time between node failure and the node being considered dead by the remaining nodes in cluster, the staging queue size grows because staging threads must wait for the acquisition of distributed locks (when processing events on activities served by failed node, or receiving requests for new sessions). If the staging queue size is too small to hold all the events until the failed node is considered dead, some events will be dropped from the staging queue (resulting in possible re-transmissions or straight-out failures).

To counter that behaviour — to ensure that the staging queue configuration is appropriate to accommodate incoming Diameter traffic until a failed node is considered dead — the administrator should adjust:

  • the maximumAge and maximumSize staging queue parameters

  • the node_abort_interval parameter (time without response before considering another node dead) in the Savanna config.properties (RHINO_HOME/etc/defaults/config/savanna and/or RHINO_HOME/node-xxx/config/savanna).

Adoption of sessions in PENDING states

The state of credit-control sessions in PendingUpdate and PendingTerminate states is changed to OPEN during adoption.

The current version of the Diameter RA does not handle the case when a client re-transmits the request on a session handled by a failed node before that session is adopted on another node, resulting in possible failure for that particular session.

Duplicate detection

The default RA configuration disallows services to handle some credit-control message duplicates by strong validation of credit-control session state against allowed credit-control message types (CC-Request-Type AVP values EVENT_REQUEST, INITIAL_REQUEST, UPDATE_REQUEST, and TERMINATION_REQUEST). Services receive only duplicate credit-control requests with CC-Request-Type AVP equal to UPDATE_REQUEST.

The InitialTerminateDuplicateHandling and LingerOnTerminate RA configuration properties can be used to cede the responsibility for detection and handling of duplicate credit-control requests to service.

Note
For details, see:
Diameter CCA, Ro, and Gx Configuration Properties.
Default RA duplicate handling

If RA configuration is not customized the default RA duplicate request handling depends on the value of CC-Request-Type AVP present in credit-control request:

  • EVENT_REQUEST or INITIAL_REQUEST — the Diameter RA detects that an EVENT_REQUEST or INITIAL_REQUEST request was already received and internally generates an error response. In case of INITIAL_REQUEST the session is also terminated.

  • UPDATE_REQUEST — no special handling of duplicated request by the Diameter RA, request is fired on existing diameter activity.

  • TERMINATION_REQUEST — the Diameter RA detects that the session was already terminated (the old session does not exist, a new session is created that receives an unexpected TERMINATION_REQUEST as its first request), and it generates an error condition .

Service duplicate handling

To enable service handling of duplicated session credit-control requests following RA configuration properties must be customized:

  • InitialTerminateDuplicateHandling — must be set to value SERVICE

  • LingerOnTerminate — must be set to value greater or equal to 1000 (the unit is milliseconds) .

Under such configuration RA fires ALL (including duplicates) session credit-control requests on diameter session.

Note The handling of duplicated event credit-control requests is not affected. Duplicated credit-control request with CC-Request-Type equal to EVENT_REQUEST are still automatically handled by RA internally generating an error response.

Example Diameter Services

This section includes:

Example Services with Diameter Simulators

Below are overviews of the Diameter example services and resource adaptor used to run them.

Example services

The Diameter example services all function similarly:

  • The initial event for the service is a MessageEvent from the example resource adaptor.

  • The service looks at the text in this event, determines the required behaviour, and executes the appropriate operation using the resource adaptor provider interface.

  • Subsequent events may use an attached activity from a previous operation.

  • A basic textual response displays to the user on the open TCP connection.

  • Detailed tracing describes the steps the service is taking.

Below are descriptions of the example services, with the simulators that they use.

Example service What it does Simulator Used

Diameter CCA

Sends Credit-Control-Request messages
and receives Credit-Control-Answer messages.

Online Charging System (OCS) Simulator

Diameter Ro

Sends Credit-Control-Request messages
and receives Credit-Control-Answer messages.

Online Charging System (OCS) Simulator

Diameter Rf

Sends Accounting-Request messages
and receives Accounting-Answer messages.

Charging Data Function (CDF) Simulator

Diameter Base (Accounting)

Sends Accounting-Request messages
and receives Accounting-Answer messages.

Charging Data Function (CDF) Simulator in Base Diameter mode [1]

Diameter Sh

Sends User-Data-Request and Profile-Update-Request messages
and receives User-Data-Answer and Profile-Update-Answer messages.+ Also supports Subscription-Notify-Request and Subscription-Notify-Answer,
and associated Push-Notification-Request and Push-Notification-Answer.

Diameter HSS Simulator

Diameter Base (Extension)

Creates a Diameter Sh message without using the Diameter Sh resource adaptor. It does this by defining a handful of Diameter Sh AVPs as extension AVPs (see Sh-AVP.xml and Diameter-Extensions.xml for the profile data), creating the User-Data-Request as an extension message and receiving the User-Data-Answer as an ExtensionAnswer event.

Diameter HSS Simulator
Note See the instructions for Running the Examples.

Example resource adaptor

The example resource adaptor provides an easy way to trigger the example services without requiring any other software (such as SIP phones or traffic generators). The example resource adaptor simply reads and writes to a TCP socket. The service can therefore be triggered by the telnet utility to send commands to the service, and results display on the same connection.

Warning The example resource adaptor is useful for simple tests and demonstrations, but it is not intended for production use; nor is it supported by OpenCloud for use outside the example services provided. It is Copyright © OpenCloud Limited 2005-2011.

Running the Examples

To install and run the an example Diameter service:

1

2

Install the service:

$ cd examples
$ ant

A message displays in the simulator log output when the resource adaptor connects to it.

3

Connect to the example resource adaptor listening on port 9999 using the telnet utility:

telnet localhost 9999

4

Try commands for the installed service, as described in the following tables.

Diameter CCA

init

send CCR messages with CC-Request-Type = INITIAL_REQUEST

up

send CCR messages with CC-Request-Type = UPDATE_REQUEST

term

send CCR messages with CC-Request-Type = TERMINATION_REQUEST

event DD

send CCR with CC-Request-Type = EVENT_REQUEST and Requested-Action = DIRECT_DEBITING

event RA

send CCR with CC-Request-Type = EVENT_REQUEST and Requested-Action = REFUND_ACCOUNT

event CB

send CCR with CC-Request-Type = EVENT_REQUEST and Requested-Action = CHECK_BALANCE

event PE

send CCR with CC-Request-Type = EVENT_REQUEST and Requested-Action = PRICE_ENQUIRY

Diameter Ro

init

send CCR messages with CC-Request-Type = INITIAL_REQUEST

up

send CCR messages with CC-Request-Type = UPDATE_REQUEST

term

send CCR messages with CC-Request-Type = TERMINATION_REQUEST

Diameter Base (Accounting)

start

send ACR with Accounting-Record-Type = START_RECORD

interim

send ACR with Accounting-Record-Type = INTERIM_RECORD

stop

send ACR with Accounting-Record-Type = STOP_RECORD

event

send ACR with Accounting-Record-Type = EVENT_RECORD

Diameter Rf

start

send ACR with Accounting-Record-Type = START_RECORD

interim

send ACR with Accounting-Record-Type = INTERIM_RECORD

stop

send ACR with Accounting-Record-Type = STOP_RECORD

event

send ACR with Accounting-Record-Type = EVENT_RECORD

sync

synchronously send ACR with Accounting-Record-Type = EVENT_RECORD

Diameter Sh

help

display available commands

udr

send a User-Data-Request

snrs1

send a Subscribe-Notifications-Request (SubsReqType=SUBSCRIBE) on a new ShClientSubscriptionActivity

snru1

send a Subscribe-Notifications-Request (SubsReqType=UNSUBSCRIBE) on an existing ShClientSubscriptionActivity

snrs2

send a Subscribe-Notifications-Request (SubsReqType=SUBSCRIBE) on a ShClientActivity

snru2

send a Subscribe-Notifications-Request (SubsReqType=UNSUBSCRIBE) on a ShClientActivity

pur

send a Profile-Update-Request

Diameter Base Extension

udr

send a `User-Data-Request `as an extension message with custom AVPs

All

help

display available commands

close

close the connection

5

Undeploy the example:

ant undeploy
Warning Each example should be undeployed before a new one is deployed. If not, the example events will be received by multiple services resulting in unpredictable behaviour.

Services using the Scenario Simulator

These services differ from other example services as they do not use the Example RA to trigger them. Instead the OpenCloud Scenario Simulator with the Diameter Scenario Pack is used. To learn how to run the client and server simulation scenarios see the Diameter Scenario Pack documentation.

The Mediation service uses two resource adaptors (CCA and Ro) to mediate between a client and server implementing those interfaces. It maps credit control requests from one interface to the other, and maps answers in the reverse direction. Since CCA and Ro are similar interfaces, the service mostly copies the AVPs 1-to-1, with the following exceptions:

  • It copies Service-Identifier, Requested-Service-Unit, and Used-Service-Unit from the Diameter CCA request message to the Diameter Ro request’s first Multiple-Services-Credit-Control AVP.

  • It applies reverse transformation for Ro answers, copying Granted-Service-Unit, Final-Unit-Indication, and Validity-Time from the Multiple-Services-Credit-Control AVP to the CCA answer message.

  • It silently drops AVPs that the outgoing interface does not support, and ignores all extension AVPs.

Note The Diameter Scenario Pack contains example scenarios for use with this Mediation service.

Credit Control Forward Service

Warning Diameter CC Forward requires a production version of Rhino as demonstrating fault-tolerance requires at least a two node cluster.

The Diameter CC Forward service is an example of a replicated service that makes use of Diameter RAs with session replication enabled (fault-tolerant mode). The Diameter CC Forward service forwards incoming CCA and/or Ro messages to configured servers. This service can be used with any CCA/Ro client supporting session fail-over and generating credit control requests and an OCS server responding to those requests. Effectively Diameter CC Forward example service acts as a proxy between the two.

Fail-over of active charging session can be invoked in two ways:

  • administratively disabling Diameter RA serving the session with reassignment of activities to another node in the cluster,

  • killing the Rhino node that is serving the session.

Example test environment using OpenCloud tools

A single machine can be used to host the entire test environment. To avoid TCP/IP port conflicts multiple IPv4 network addresses from the 127.0.0.0/8 loopback subnet are used.

The OpenCloud Scenario Simulator with the Diameter Scenario Pack can be used to simulate client in this scenario but due to lack of session fail-over support in current version of Diameter Scenario Pack ( 2.5.0.1 ) this is not a straightforward process. The server can be simulated using Online Charging System (OCS) Simulator. To make up for lack of session fail-over support in the client another Rhino cluster with Diameter CC Forward service is used. This additional Rhino instance acts as a proxy server between OpenCloud Scenario Simulator and Rhino cluster used for testing the fail-over behaviour.

Example fail-over testing environment
Figure 1. Example fail-over testing environment

There are two separate Rhino clusters on the diagram. The first consists of nodes 101 and 102, while nodes 201 and 202 constitute the second. The first - Front cluster is used to deliver client session fail-over support, while the second - Back cluster is used to test the RA and example service behaviour in node failure scenario.

Prerequisites

  • Production Rhino with a valid license (including the license for Diameter RA)

  • Scenario Simulator with Diameter Scenario Pack (recent Scenario Simulator Package versions are bundled with Diameter Scenario Pack)

Environment setup:

  1. Install two separate Rhino clusters, remember to select different cluster ids and ports for both clusters, for details refer to Rhino Documentation.

  2. Create two nodes in each of the clusters (node 101, 102 in the Front cluster and nodes 201, 202 in the Back cluster).

  3. Unpack the Diameter Resource Adaptors package into each Rhino Cluster installation directory.

  4. Change the profile.import.file in example service configuration file examples/ccforward/build.properties to:

    • DiameterConfigFront.xml for the Front cluster

    • DiameterConfigBack.xml for the Back cluster

  5. Change the diameter configuration for OCS simulator to match the Back cluster configuration. That is, in file simulators/ocs-simulator/config/DiameterConfig.xml change the value of listenAddress element in server profile to 127.3.0.1.

  6. Install and configure OpenCloud Scenario Simulator by following instructions in examples/ccforward/diameter-examples/README-ccforward-example.txt.

  7. Start the reconfigured OCS simulator using script simulators/ocs-simulator/ro-simulator.sh.

  8. Start nodes of the Back cluster and install the Diameter CC Forward service (run ant in Diameter Resource Adaptors package examples/ccforward of the Back Rhino Cluster).

  9. Start nodes of the Front cluster and install the Diameter CC Forward service (run ant in Diameter Resource Adaptors package examples/ccforward of the Front Rhino Cluster).

  10. Optionally deactivate the creditcontrol-0 Diameter CCA entity, as the example scenario distributed with Scenario Simulator uses the Diameter Ro Application.

  11. Start the Scenario Simulator (refer to examples/ccforward/diameter-examples/README-ccforward-example.txt) and run one of the loaded scenarios.

After that you can experiment with session fail-over by inducing session adoption in different session states through customizing timeouts and delays between messages in the example scenarios used in Scenario Simulator. Note that routing table configuration of the Front cluster is such that node 202 of the Back cluster is always preferred when reachable.

1. To start the CDF simulator in Base Diameter mode, execute the acct-simulator.sh script instead of the cdf-simulator.sh script.