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:
|
|
|
|
|
|
|
|
|
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
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:
-
Deploy the Diameter base types library that contains the Java types used by all Diameter resource adaptors.
-
Deploy the Diameter profile specs.
-
Deploy the Netty library shared by all Diameter resource adaptors (and some others).
-
Deploy a Diameter resource adaptor type.
-
Deploy a Diameter resource adaptor.
-
Create a Diameter configuration profile (and profile table).
-
Create a Diameter resource adaptor entity.
Configuring Diameter Resource Adaptors
You configure Diameter resource adaptors using:
-
resource adaptor configuration properties — to specify timeouts, transport security settings, thread pool settings, and so on
-
SLEE profiles — to specify peer connections, realm routing rules, and extension AVPs.
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? |
---|---|---|---|---|
|
Diameter Configuration Profile from which to load the Diameter stack configuration |
valid profile name specified as |
No |
|
|
time between polling for changes to ConfigurationProfile, in milliseconds |
|
|
Yes |
|
Diameter Extension AVP Set profile for configuring extension AVPs (if specified) |
profile name specified as |
Yes |
|
|
time between polling for changes to |
|
|
Yes |
|
timeout for waiting for outgoing transport connection establishment |
number of milliseconds |
|
Yes |
|
timeout for waiting for responses before firing a Timeout event |
number of milliseconds |
|
Yes |
|
timeout for waiting for watchdog responses (RFC3539 timer Tw) |
number of milliseconds |
|
Yes |
|
delay before reconnecting (RFC6733 timer Tc) |
number of milliseconds |
|
Yes |
|
if true, always attempt to reconnect even if the server sent a DPR with Disconnect-Cause set to |
|
|
Yes |
|
service to fire events to (if specified) |
Service ID as full display string as shown by management commands |
Yes |
|
|
size of thread pool for decoding incoming diameter messages |
|
|
No |
|
size of the task queue of thread pool for decoding incoming diameter messages |
|
|
No |
|
number of IO threads serving incoming connections |
|
|
No |
|
number of IO threads serving outgoing connections |
|
|
No |
|
a set of Supported-Vendor-Id AVP values used in CER and CEA, multiple comma separated values can be specified |
integer number (from |
No |
|
|
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 |
|
|
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? |
---|---|---|---|---|
|
value to put into the |
grouped AVP containing a |
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? |
---|---|---|
|
value for Ts as defined by section 8.2 of RFC 6733 — the timeout value for stateful accounting sessions |
Yes |
|
value to include (if specified) in an |
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? |
---|---|---|---|
|
3GPP version of protocol supported by the resource adaptor |
two forms allowed:
|
No |
3GPP version
Your SBB must use the provider factory method and the types sub-package that matches the value you specify, unless the Slee3GPPVersion
is set. 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
|
Diameter SLEE 3GPP configuration properties
Diameter Ro and Rf resource adaptors use this configuration property to specify a different 3GPP version for internal use (by the SLEE) than that used externally (on the network). The Slee3GPPversion
specifies the API used by any SLEE application built using the Diameter Ro or Rf resource adaptors. If configured differently from the 3GPPVersion then all diameter messages will be converted as follows:
-
Incoming messages received from the network will be converted from the received version (
3GPPVersion
) to the SLEE version (Slee3GPPVersion
) before being processed by a SLEE application -
Outgoing messages will be converted from the internal version (
Slee3GPPVersion
) to the external version (3GPPVersion
) before being sent on the network -
Any AVPs not valid or without equivalent AVPs in either target version will be lost.
Property | What it specifies | Values | Active reconfig? |
---|---|---|---|
|
3GPP version of protocol supported by the SLEE(application) |
If specified, two forms allowed:
Otherwise, |
No |
SLEE 3GPP version
Your SBB must use the provider factory method and the types sub-package that matches the Slee3GPPVersion
you specify, if notspecified the 3GPPVersion
provider factory should be used. For example, for Ro V12.11.0
(Slee3GPPVersion
=Vcb0
) or (Slee3GPPVersion
=12.11.0
), you would use the provider method
RoProviderFactory.getRoProviderVcb0()
and import your Diameter types from the package
org.jainslee.resources.diameter.ro.types.vcb0
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? |
---|---|---|---|---|
|
value to put into the |
string value specified as |
|
Yes |
|
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) |
|
|
Yes |
|
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 |
|
|
No |
|
start replicating new Diameter sessions on creation:
|
|
|
Yes |
|
timeout for waiting for responses before firing a |
number of milliseconds; |
|
Yes |
|
Controls Tcc session supervision timer driven behaviour (RFC 4006 section 13 and section 7).
|
integer value |
|
No |
|
provides a default value for |
optional string parameter; if provided, must be one of: |
Yes |
|
|
provides a default value for |
optional string parameter; if provided, must be one of: |
Yes |
|
|
provides a default value for |
optional string parameter; if provided, must be one of: |
Yes |
|
|
switch the responsibility for handling of duplicated
|
string parameter; must be one of: |
|
Yes |
|
delay ending diameter activity by |
number of milliseconds; |
|
Yes |
|
session inactivity timeout used by RA when handling SLEE |
number of milliseconds |
|
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? |
---|---|---|
|
product name to use in Product-Name AVPs generated by the stack |
Yes |
|
value to be used as Vendor-Id AVP in CER/CEA messages default value is |
Yes |
|
version number to use in all Firmware-Revision AVPs generated by the stack must be a positive int |
Yes |
|
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? |
---|---|---|
|
whether to use |
Yes |
|
if true, then any peer may connect to this node; |
Yes |
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 to use in all Origin-Host AVPs; |
No |
|
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 |
|
extra addresses to bind SCTP server channels to (SCTP multi-homing) multiple addresses may be separated by commas |
Yes |
|
listen port |
Yes |
|
transport(s) to listen on values can be |
Yes |
Multi-node host configuration
Attribute | What it specifies | Active reconfig? |
---|---|---|
|
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 |
Yes |
|
host names, one per node, in the same order as NodeIDs used for the each hostname must be unique |
No |
|
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 |
|
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 |
|
Diameter ports, one per node, in the same order as NodeIDs used for the listen port on each node ignored if |
Yes |
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.
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? |
---|---|---|
|
host of remote Diameter peer |
Yes |
|
port of remote Diameter peer |
Yes |
|
(optional) address to override PeerHost when resolving address for outgoing connections must be a numeric IP address if not specified, the host set in |
Yes |
|
whether to connect to the remote peer at startup must be |
Yes |
|
whether to establish TLS secure session with peer defined in PeerHost |
Yes |
|
value required (exact string match) for owner-distinguished name with certificate from peer (required if defined) example value: |
Yes |
|
Diameter Application ID |
Yes |
|
Vendor ID must be 0 for IETF-specified applications, or an IANA-assigned private enterprise number |
Yes |
|
must be |
Yes |
Advanced peer and realm configuration
Attribute | What it specifies | Active reconfig? |
---|---|---|
|
valid XML document for peer table configuration |
Yes |
|
valid XML document for realm table configuration |
Yes |
|
select outgoing request routing algorithm value must be one of: |
Yes |
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.
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.
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.1.0//EN" "http://www.opencloud.com/dtd/diameter-peer-table-1.1.0.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 | ||
---|---|---|---|---|---|
|
file to load certificate key store from |
filename on the local file system, or URL
|
|||
|
password for certificate key store |
any string |
|||
|
file to load trust key store from |
filename on the local file system, or URL
|
|||
|
password for trust key store |
any string |
|||
|
comma-separated list of TLS cipher suites to be enabled for use when establishing TLS handshake |
any values supported by virtual machine vendor; |
|||
|
time after which TLS session should be invalidated and new session will be established |
number of seconds; |
|
||
|
is downgrade to TLS support in accordance with RFC 3588 allowed. |
if
|
|
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
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 |
---|---|---|
|
code for this AVP |
to look up this extension AVP definition |
|
AVP name |
(not used — for reference only) |
|
AVP type |
by the stack to encode and decode the AVP |
|
Mandatory Rule setting for this AVP Valid values are defined by the |
|
|
Protected Rule setting for this AVP Valid values are defined by the |
|
|
vendor ID code for this AVP |
to look up this extension AVP definition |
Diameter Extension AVP Set
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 |
---|---|
|
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.
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 |
||
ALWAYS |
As well as the
|
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 |
|
requests for which session already exists |
|
Server mode |
all requests |
all requests |
|
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 or (optionally for Rhino 2.6.2 and higher) written to an external key/value store.
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.
Using Rhino Replicated Storage
(This is the only replication method available in Rhino versions less than 2.6.2)
To use this method:
-
the namespace in which the application is running must be configured to use the
DomainedMemoryDatabase
.
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.
Using Key/Value Store
(This replication method is only available in Rhino versions 2.6.2 and higher)
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 |
---|---|
|
Tells whether moving the credit-control message stream to a backup server during an ongoing credit-control session is supported. |
|
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. |
|
Used during one-time event credit-control ( |
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 toFAILOVER_SUPPORTED
, the session is always adopted. -
If
CC-Session-Failover
is NOT equal toFAILOVER_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 |
---|---|---|
|
optional string parameter If provided must, be one of:
|
(otherwise |
|
optional string parameter If provided must, be one of:
|
|
|
optional string parameter If provided must, be one of:
|
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.
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 |
The |
PendingInitial, PendingUpdate |
when the session’s |
Other |
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.
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.
Credit-control routing behaviour — influenced by the Tx Timer, 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 |
attempt re-transmission |
CONTINUE, RETRY_AND_TERMINATE |
attempt re-transmission |
attempt re-transmission |
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
orTERMINATION_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
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.
For the lock to be acquired on a node other than the node that previously owned the lock, one of two events must occur:
|
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
andmaximumSize
staging queue parameters -
the
node_abort_interval
parameter (time without response before considering another node dead) in the Savannaconfig.properties
(RHINO_HOME/etc/defaults/config/savanna
and/orRHINO_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.
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
orINITIAL_REQUEST
— the Diameter RA detects that anEVENT_REQUEST
orINITIAL_REQUEST
request was already received and internally generates an error response. In case ofINITIAL_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 unexpectedTERMINATION_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 valueSERVICE
-
LingerOnTerminate
— must be set to value greater or equal to1000
(the unit is milliseconds) .
Under such configuration RA fires ALL (including duplicates) session credit-control requests on diameter session.
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. |
Key/Value Replicated Storage
Key/value replicated storage uses an external database cluster to store session state.
See Replication Support Services for information on the Rhino key/value store as well as the Session Ownership Facility. |
To use this replication method:
-
the application must be deployed on Rhino 2.6.2 or higher,
-
the Rhino Session Ownership Facility must be configured,
-
a Key/Value Store must be configured,
-
the namespace in which the application is running must have the Session Ownership Facility enabled and be configured to use the
KeyValueDatabase
replicated storage resource, and -
the service managing the session must write a Diameter session ownership record linked to the convergence name session ownership record.
When using this method, the ReplicateByDefault
RA configuration property controls whether sessions are written to the key/value store immediately on creation (true
) or only after startReplicating()
is called on a particular session (false
).
When session replication is enabled, credit-control session state is written to the external key/value store. If a node handling a charging session within a cluster fails after any hardware, software, or network error, the next event related to that session which occurs on a different node in the cluster will cause the credit-control session to be "adopted" by that node. The adoption is performed using a CAS race on the convergence name session ownership record.
The event triggering the adoption race could be any event related to the overall session such as:
-
a RAR or ASR sent from the OCS to a different node,
-
a SIP dialog routed to a different node, or
-
a timer event from a redundantly armed session timer.
Message proxying
This method also support proxying of Re-Auth-Request
and Abort-Session-Request
messages between nodes.
Proxying could occur if, for example, a client charging session has been adopted by another node and the original node handling the session has come back up. The OCS could send a RAR or ASR to the original node even though a new node is now handling the session. In this case, the session ownership record will be consulted and the request will be proxied to the owning node. The corresponding RAA or ASA will be proxied back to the receiving node to send back to the OCS.
Session Ownership
The ownership of a session is determined by the convergence name session ownership record. Each protocol involved in the overall session also has its own record linked to the convergence name record. For the key/value replication method to work, these session ownership records must be written by the application.
The convergence name session ownership record is created and managed by Rhino. A service can retrieve it using RhinoSbbContext.getConvergenceNameSessionOwnershipRecord()
.
The Diameter session ownership record must be written by the service with:
-
its primary key set to the value returned by
getTrackingKey()
on the CCA/Ro/Gx charging session activity, -
an owner URI set to the value returned by
getInternalASURI()
on the CCA/Ro/Gx provider, and -
an associated record attribute with the value being the primary key of the convergence name record.
Example for Diameter Ro
The following is a brief example of a service using the Diameter Ro RA for a fault-tolerant client charging session using the key/value store.
If the Diameter Ro RA is configured with ReplicateByDefault
set to false
, then the service should call startReplicating()
on the client charging session when the application determines that the overall session (likely involving other protocols) is confirmed.
RoClientSessionActivity roClientSessionActivity = (RoClientSessionActivity) aci.getActivity();
roClientSessionActivity.startReplicating();
At the same time the service should write a session ownership record for the Diameter Ro charging session:
RoClientSessionActivity roClientSessionActivity = (RoClientSessionActivity) aci.getActivity();
// Values for the Diameter session ownership record
String roTrackingKey = roClientSessionActivity.getTrackingKey();
String ownerUri = roProviderFactory.getInternalASURI().toString();
String associatedRecordKey = ((RhinoSbbContext) getSbbContext()).getConvergenceNameSessionOwnershipRecord().getPrimaryKey()
// Build the record
SessionOwnershipRecord.Builder recordBuilder = SessionOwnershipRecord.newBuilder()
.setPrimaryKey(roTrackingKey)
.addOwnerURI(ownerUri);
recordBuilder.addAttribute(SessionOwnershipRecord.ASSOCIATED_RECORD_ATTRIBUTE_NAME, associatedRecordKey);
SessionOwnershipRecord record = recordBuilder.build();
// Create an activity to handle the write operation
SessionOwnershipActivity sessionOwnershipActivity = sessionOwnershipProvider.createSessionOwnershipActivity();
// To be notified of the result of the write operation the SBB must
// attach to the session ownership activity ACI and handle the
// corresponding SessionOwnershipWriteResultEvent.
ActivityContextInterface aci = sessionOwnershipAciFactory.getActivityContextInterface(sessionOwnershipActivity);
aci.attach(getSbbLocalObject());
// write the session ownership record asynchronously
sessionOwnershipActivity.storeRecord(record);
When the charging session has finished (on receipt of CCA-T or an unrecoverable error) the service should remove the session ownership record:
String roTrackingKey = roClientSessionActivity.getTrackingKey();
// Create an activity to handle the delete operation
SessionOwnershipActivity sessionOwnershipActivity = sessionOwnershipProvider.createSessionOwnershipActivity();
// To be notified of the result of the delete operation the SBB must
// attach to the session ownership activity ACI and handle the
// corresponding SessionOwnershipWriteResultEvent.
ActivityContextInterface aci = sessionOwnershipAciFactory.getActivityContextInterface(sessionOwnershipActivity);
aci.attach(getSbbLocalObject());
// delete the session ownership record asynchronously
sessionOwnershipActivity.deleteRecord(roTrackingKey, Collections.<String>emptySet());
Example Diameter Services
This section includes:
-
descriptions of example services, which use the Diameter simulators and example resource adaptor
-
instructions for running the examples
-
-
descriptions of the Mediation and Credit Control Forward example services, which use the OpenCloud Scenario Simulator
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 |
|
Diameter Ro |
Sends |
|
Diameter Rf |
Sends |
|
Diameter Base (Accounting) |
Sends |
Charging Data Function (CDF) Simulator in Base Diameter mode [1] |
Diameter Sh |
Sends |
|
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 |
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.
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 |
Start the simulator for that service. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
2 |
Install the service: 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
Diameter Ro
Diameter Base (Accounting)
Diameter Rf
Diameter Sh
Diameter Base Extension
All
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
5 |
Undeploy the example: ant undeploy
|
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
, andUsed-Service-Unit
from the Diameter CCA request message to the Diameter Ro request’s firstMultiple-Services-Credit-Control
AVP. -
It applies reverse transformation for Ro answers, copying
Granted-Service-Unit
,Final-Unit-Indication
, andValidity-Time
from theMultiple-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.
The Diameter Scenario Pack contains example scenarios for use with this Mediation service. |
Credit Control Forward Service
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.
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.
-
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)
-
Install two separate Rhino clusters, remember to select different cluster ids and ports for both clusters, for details refer to Rhino Documentation.
-
Create two nodes in each of the clusters (node
101
,102
in the Front cluster and nodes201
,202
in the Back cluster). -
Unpack the Diameter Resource Adaptors package into each Rhino Cluster installation directory.
-
Change the
profile.import.file
in example service configuration fileexamples/ccforward/build.properties
to:-
DiameterConfigFront.xml
for the Front cluster -
DiameterConfigBack.xml
for the Back cluster
-
-
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 oflistenAddress
element inserver
profile to127.3.0.1
. -
Install and configure OpenCloud Scenario Simulator by following instructions in
examples/ccforward/diameter-examples/README-ccforward-example.txt
. -
Start the reconfigured OCS simulator using script
simulators/ocs-simulator/ro-simulator.sh
. -
Start nodes of the Back cluster and install the Diameter CC Forward service (run
ant
in Diameter Resource Adaptors packageexamples/ccforward
of the Back Rhino Cluster). -
Start nodes of the Front cluster and install the Diameter CC Forward service (run
ant
in Diameter Resource Adaptors packageexamples/ccforward
of the Front Rhino Cluster). -
Optionally deactivate the
creditcontrol-0
Diameter CCA entity, as the example scenario distributed with Scenario Simulator uses the Diameter Ro Application. -
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.
Service Assurance Server (SAS) Tracing
The Diameter resource adaptor is integrated with the Metaswitch Service Assurance Server (SAS). SAS provides a mechanism to record and search detailed end-to-end tracing of call handling.
See the SAS Facility section in the Rhino extended API documentation for more information about SAS tracing.
SAS tracing is supported on Rhino versions 2.6 and later. The Diameter resource adaptor can be used with earlier Rhino versions if the Rhino API Compatibility SLEE library is deployed. The script that deploys the Diameter services included in the resource adaptor package has an example of how the library is deployed. |
The Diameter CCA and Ro resource adaptors automatically perform SAS tracing, if it is enabled in Rhino.
Diameter server sessions (incoming requests)
The resource adaptor will create a new SAS trail for charging sessions and incoming immediate event charging. The requests will then be logged on this trail.
Diameter client sessions (outgoing requests)
For Diameter client sessions, the resource adaptor will also create a new SAS trail. Correlations with other trails must be done by getting the trail from the activity after the first request is sent.
SAS markers
When creating a SAS trail, the resource adaptors will raise a SAS marker for trail correlation. They raise a GENERIC_CORRELATOR_MARKER
containing the Session-Id
AVP.
SAS events
---
version: 0.1
events:
SENDING_MESSAGE:
summary: 'Sending Diameter {{ var_data[2] | decode_diameter_summary }}'
details: | Sending Diameter {{ var_data[2] | decode_diameter_summary }} to "{{ var_data[1] }}" <sas:fixed-width-font>{{ var_data[2] | decode_diameter_details }}</sas:fixed-width-font>
level: 60
call_flow:
data: '{{ var_data[2] | binary }}'
protocol: _Diameter
direction: out
local_address: "{{var_data[0]}}:{{static_data[0]}}"
remote_address: "{{var_data[1]}}:{{static_data[1]}}"
RECEIVED_MESSAGE:
summary: 'Received Diameter {{ var_data[2] | decode_diameter_summary }}'
details: | Received Diameter {{ var_data[2] | decode_diameter_summary }} from "{{ var_data[1] }}" <sas:fixed-width-font>{{ var_data[2] | decode_diameter_details }}</sas:fixed-width-font>
level: 60
call_flow:
data: '{{ var_data[2] | binary }}'
protocol: _Diameter
direction: in
local_address: "{{var_data[0]}}:{{static_data[0]}}"
remote_address: "{{var_data[1]}}:{{static_data[1]}}"
MESSAGE_RECEIVED_IN_STATE:
summary: 'Message received in Peer FSM State {{ var_data[0] }}'
level: 20
MESSAGE_FILTERED_BY_FSM_STATE:
summary: 'Message filtered by Peer FSM State'
level: 20
SESSION_ID_MISSING:
summary: 'Session-Id missing from message'
level: 20
INTERNAL_PROCESSING_ERROR:
summary: 'Diameter RA experienced an internal processing error {{ var_data[0] }} {{ var_data[1] }}'
details: | Diameter RA experienced an internal processing error {{ var_data[0] }} {{ var_data[1] }} {{ var_data[2] }}
level: 40
RETRANSMIT:
summary: 'Attempting retransmit of Diameter request'
level: 40
SENDING_PROXIED_MESSAGE:
summary: 'Sending proxied Diameter {{ var_data[2] | decode_diameter_summary }}'
details: | Sending proxied Diameter {{ var_data[2] | decode_diameter_summary }} to "{{ var_data[1] }}" <sas:fixed-width-font>{{ var_data[2] | decode_diameter_details }}</sas:fixed-width-font>
level: 60
call_flow:
data: '{{ var_data[2] | binary }}'
protocol: _Diameter
direction: out
local_address: "{{var_data[0]}}"
remote_address: "{{var_data[1]}}"
RECEIVED_PROXIED_MESSAGE:
summary: 'Received proxied Diameter {{ var_data[2] | decode_diameter_summary }}'
details: | Received proxied Diameter {{ var_data[2] | decode_diameter_summary }} from "{{ var_data[1] }}" <sas:fixed-width-font>{{ var_data[2] | decode_diameter_details }}</sas:fixed-width-font>
level: 60
call_flow:
data: '{{ var_data[2] | binary }}'
protocol: _Diameter
direction: in
local_address: "{{var_data[0]}}"
remote_address: "{{var_data[1]}}"