Service Configuration
Introduction
A JSLEE Diameter service is deployed with one or more endpoints configured. Each endpoint is configured as an Agent for proxy/translation/relay, or as a charging & control endpoint, and will be configured either as a server, or a client.
Configuration options fall into four general groups:
- Configuration required for network connectivity, including message timers.
- Configuration required for correctly authenticating and communicating with Diameter peers.
- Configuration required for processing and reacting to inbound messages, and for sending outbound messages.
- Configuration for determining the type of Diameter application for each endpoint.
The basic configuration for the Diameter service is the same as all other services, with the correct handler class and instance count needing configuration:
{
"diameter": {
"handler": "nz.co.nsquared.slee.diameter.DiameterVerticle",
"instance-count": 1,
"configuration": {
"endpoints": [
{
/* endpoint configuration */
"applications": [
{
/* application configuration */
}
]
}
]
}
}
}
Each Diameter endpoint may be a Diameter client, or Diameter server. The most basic
Diameter endpoint configuration determines this within an endpoints
hash object:
{
"endpoints": [
{
"is-server": true
}
]
}
The is-server
field, when set to true, determines this endpoint as a listening endpoint
(and will receive Diameter request messages). If set to false, this endpoint connects to
a remote server (and will send Diameter request messages).
The Diameter Client page covers the Diameter client configuration in further detail.
Inherited Configuration
As a Diameter service will likely define one or more Diameter endpoints. It is recommended that most endpoint configuration is not defined directly within the endpoint, but rather is imported using the JSLEE import configuration.
A general diameter configuration file may be defined and included in the overall configuration. The file /opt/nsquared/jslee/etc/common/diameter/relay-server-endpoint.json
, included with all installations, defines an example Diameter relay server endpoint.
"endpoints": [{
// The interface the server listens on
// Edit /etc/hosts and define the interface there,
// rather than altering this file.
"interface": "jslee-diameter-if",
// and the port it listens on.
"port": 3868,
// Is this server connection enabled by default on startup.
// Being enabled means it will start listening immediately
// on port 3868 without manual intervention to enable it.
"is-enabled": true,
// As this is a server, is-server must be true. Otherwise
// a remote address to connect to must be provided.
"is-server": true,
// The diameter Origin-Host value, which can define the name of this
// interface as well as the origin realm.
// The origin-host, confusingly, is the fully qualified hostname
// (basically)
"origin-host": "pn01.nsquared.nz",
// derived from origin-host
// "origin-realm": "nsquared.nz",
// name can be derived from origin-host, but since we may have two endpoints
// with the same origin-host value, we should be explicit.
"name": "pn01s",
// Our minimal list of AVPs we know about. The full AVP definitions
// are pulled from CSV files provided as part of the compiled codebase.
"avp-definitions": [
"IETF RFC 6733",
"3GPP TS 32.299"
],
// The value to use when sending the product name in Diameter messages
"product-name": "N2HPP",
// The vendor ID to represent our Diameter server as.
"vendor-id": 10415,
// The value of the Diameter firmware revision. For now, 1 is appropriate.
"firmware-revision": 1,
// Diameter AVP "Supported-Vendor-Id":
// The list of supported vendor IDs to publish.
"supported-vendor-ids": [
10415
],
// pull in defined timouts for handling late responses.
"time-limits": {
"__include": "etc/common/diameter/time-limits.json"
},
// pull in error handling, i.e. how to respond to specific
// events which are technically errors against the specification
"error-handling": {
"__include": "etc/common/diameter/error-handling.json"
},
// Pull in validation configuration, for use when validation
// is enabled and the system should explicitly validate inbound and
// outbound messages before sending and on receiving.
//
// Note that validation is semantic, applying both validation
// as per the spec, and also deployment specific validation.
"validation": {
"__include": "etc/common/diameter/validation.json"
},
// The actual application
"applications": [
{
// a Relay Agent
"class-path": "nz.co.nsquared.slee.diameter.application.agent.Agent",
// The JSLEE service name to send all messages to for relay.
"routing": [
{
"condition": "false",
"destination": "diam01c"
}
]
}
]
}]
With the main server configuration reusing this configuration as many times as required, e.g.
/opt/nsquared/jslee/etc/server.json
could then contain:
{
"diam01s": {
"handler": "nz.co.nsquared.slee.diameter.DiameterVerticle",
"instance-count": 1,
"configuration": {
"endpoints": [
{
"__include": "/opt/nsquared/jslee/etc/common/diameter/relay-server-endpoint.json",
}
]
}
},
"diam01c": {
"handler": "nz.co.nsquared.slee.diameter.DiameterVerticle",
"instance-count": 1,
"configuration": {
"endpoints": [
{
"__include": "/opt/nsquared/jslee/etc/common/diameter/relay-client-endpoint.json",
"remote-server": "10.42.2.52"
}
]
}
}
}
Basic Configuration
The following basic configuration is valid for each endpoint:
Field | Type | Required? | Default | Description |
---|---|---|---|---|
port |
Integer | No | 3868 |
Server endpoints: The TCP port to listen on. Client endpoints: The TCP port to connect to. |
is-enabled |
Boolean | No | true |
Whether this endpoint is enabled or disabled by default (on service startup). |
is-server |
Boolean | No | true |
Must be set to true for servers, and false for clients. |
interface |
String | No | 0.0.0.0 |
The IP address of the local interface to bind to. If left as the default value, the server will bind to all interfaces. |
remote-server |
String | No | - | When is-server is false (i.e. this endpoint is a Diameter client), the remote server is mandatory and is the host (IP or name) to connect to. |
Diameter peers must communicate basic routing and protocol information. The information that the JSLEE Diameter service requires to perform these basic tasks is provided in the following configuration variables:
Field | Type | Required? | Default | Description |
---|---|---|---|---|
name |
String | No | - | The name of the endpoint, for use in JSLEE addressing, and in debug, logging and EDRs. If not defined, it must be able to be derived from the origin-host field. |
origin-host |
String | No | - | The Diameter Origin-Host value, to use when communicating with remote endpoints over Diameter. If not defined, it must be able to be derived from the name and origin-realm fields. |
origin-realm |
String | No | - | The Diameter Origin-Realm value, to use when communicating with remote endpoints over Diameter. If not defined, it must be able to be derived from the origin-host field. |
avp-definitions |
Array of String | No | - | A list of strings determining which AVP sources the endpoint will recognise. While not required, it is almost certainly undesirabled to leave this undefined. |
product-name |
String | No | N-Squared Diameter |
The product name of the N-Squared JSLEE Diameter service. |
vendor-id |
Integer | No | 0 |
The vendor ID to represent our diameter as. Defaulting to 0, the JSLEE diameter inteface doesn’t publish a custom vendor ID. |
firmware-revision |
Integer | No | 1 |
The revision of the JSLEE diameter interface. This will be altered by N-Squared when appropriate. |
supported-vendor-ids |
Array of Integer | No | A list of vendor IDs of vendors which the JSLEE Diameter service understands. The list of vendor IDs provided by this configuration option will be published to peers in Supported-Vendor-Id AVPs. |
|
host-ip-addresses |
Array of String | No | The list of host IP addresses this Diameter peer publishes to its peers during capabilities exchange. |
Timers
The following configurable timers are defined by the Diameter Service. These timers must be defined
in a subsection time-limits
. The defaults, given in the file /opt/nsquared/jslee/etc/common/diameter/time-limits.json
are defined with the following configuration:
"time-limits": {
"initial-cer-time-limit-ms": 5000,
"cea-time-limit-ms": 500,
"dwr-interval-ms": 30000,
"dwa-time-limit-ms": 500,
"raa-time-limit-ms": 500,
"dpa-time-limit-ms": 500,
"other-answer-time-limit-ms": 1000
}
Field | Type | Required? | Default | Description |
---|---|---|---|---|
initial-cer-time-limit-ms |
Integer | No | 5000 |
The maximum time in milliseconds between a TCP/IP network connection being made, and the CER being received. If not received, the connection is dropped. For server connections only. |
cea-time-limit-ms |
Integer | No | 500 |
The maximum time in milliseconds between sending a CER and the CEA being received. If not received, the connection is dropped. For client connections only. |
dwr-interval-ms |
Integer | No | 30000 |
The number of milliseconds a connection is to stay idle before a DEVICE_WATCHDOG request is sent. If set to 0, no DEVICE_WATCHDOG requests will be sent. Applies to clients and server connections. |
dwa-time-limit-ms |
Integer | No | 500 |
The maximum time in milliseconds between sending a DEVICE_WATCHDOG request and the DEVICE_WATCHDOG answer being received. If not received, the connection is dropped. |
raa-time-limit-ms |
Integer | No | 500 |
The maximum time in milliseconds between sending a RE-AUTH request and the answer being received. If not received, the connection is dropped. |
dpa-time-limit-ms |
Integer | No | 500 |
The maximum time in milliseconds between sending a DISCONNECT_PEER request and the answer being received. If not received, the connection is dropped. |
other-answer-time-limit-ms |
Integer | No | 1000 |
The maximum time in milliseconds between sending a message and receiving the response, for messages without their own timer. It is recommended this timer is explicitly set for each deployment to account for the performance characteristics of their OCS. |
Host IP Addresses
During capabilities exchange, the Diameter protocol requires all Diameter peers to publish the IP address
(or addresses) where it can be reached. These are transmitted in the Host-IP-Address
AVP, and at least
one must be provided.
Normally a JSLEE Diameter endpoint will be able to identify the appropriate host IP address to publish,
however if it is required that this automatic selection is overridden, the host-ip-addresses
configuration
option can be provided.
Each host IP address must be given as a string:
"host-ip-addresses": [
"127.0.0.1",
"192.168.70.31",
"::1"
]
AVP Definition Configuration
The Diameter protocol requires all Diameter peers to understand a certain set of AVPs. Determining
which AVPs are available is a configuration option called avp-definitions
. This option is an array of strings:
"avp-definitions": [
"IETF RFC 6733",
"3GPP TS 32.299"
]
Even for agents which relay Diameter messages, it is not sufficient to understand “IETF RFC 6733”. All AVPs that will be received and marked as mandatory must be documented. Additional AVP sources may be defined, including custom sources.
Field | Type | Required? | Default | Description |
---|---|---|---|---|
avp-definitions |
Array of String | No | - | The list of AVP definition files to load. |
It is recommended that at the minimum the following AVPs are defined:
"avp-definitions": [
"IETF RFC 6733",
"3GPP TS 32.299"
]
Error Handling
As Diameter is a protocol with a complex state machine, many real-world features are implemented by different vendors to varying degrees, and with varying semantics.
The N-Squared Diameter stack provides some management control over situations where implementation differences might cause errors in message processing
Error handling is defined in a subsection error-handling
. The defaults, given in the file /opt/nsquared/jslee/etc/common/diameter/error-handling.json
are defined with the following configuration:
"error-handling": {
"request-decode-avp-decode-error-action": "Send Protocol Error",
"request-decode-unsupported-avp-error-action": "Send Protocol Error",
"request-decode-other-protocol-error-action": "Send Protocol Error",
"request-process-avp-data-type-mismatch-action": "Send Protocol Error",
"request-process-unsupported-avp-action": "Send Protocol Error",
"response-decode-avp-decode-error-action": "Drop Message",
"response-decode-unsupported-avp-error-action": "Drop Message",
"response-decode-other-protocol-error-action": "Drop Message",
"response-process-avp-data-type-mismatch-action": "Drop Message",
"response-process-unsupported-avp-action": "Drop Message"
}
Field | Type | Required? | Default | Scenario |
---|---|---|---|---|
request-decode-avp-decode-error-action |
String | No | “Attempt Message Processing” | When an AVP is encountered which could not be decoded. This might occur when a known AVP type is encountered, but the bytes are not a valid value for the type. |
request-decode-unsupported-avp-error-action |
String | No | “Attempt Message Processing” | When an AVP is encountered which is itself unknown - most likely due to a missing AVP type definition. |
request-decode-other-protocol-error-action |
String | No | “Attempt Message Processing” | This error occurs when more general decoding errors occur, such as when a message cannot be decoded due to insufficient bytes being available. |
request-process-avp-data-type-mismatch-action |
String | No | “Attempt Message Processing” | This error occurs when programming executing in the JSLEE (eg. as part of a script) attempts to incorrectly encode an AVP as the wrong type. |
request-process-unsupported-avp-action |
String | No | “Attempt Message Processing” | This error occurs when programming executing in the JSLEE (eg. as part of a script) attempts to process an AVP which is unknown. |
Each request-
configuration option has a similar response-
configuration option, which applies when the error
is encountered during the handling of a Diameter response, rather than Diameter request.
Each field value defines the action the system should take on the error as it is encountered. The following options are available:
Action | Description |
---|---|
Attempt Message Processing | The AVP is skipped, and processing continues as if the AVP was not included in the message. |
Disconnect | The connection to the Diameter peer which originated the message with the failing AVP is disconnected. |
Quiesce | The connection to the Diameter peer which originated the message with the failing AVP is forced to enter a quiescing state, as if the user manually disabled the connection. |
Drop Message | The message with the problematic AVP is dropped silently, with no further processing. |
Send Protocol Error | A response is sent back to the originator of the Diameter message with the problematic AVP. The response indicates a protocol error has occurred. |
Suppressing Warnings
Some scenarios are considered warnings by the JSLEE diameter gateway, yet may occur under normal processing. It is possible to alter the importance of these messages by defining JSON configuration as part of a Diameter endpoint:
"log-action-on": {
"forced-cleanup-of-active-subsessions": "none",
"termination-of-unknown-subsession": "none",
"termination-of-unknown-session": "none"
}
Each option may be one of the following values:
none
No message is printed.debug
A debug message is printed.info
An information message is printed.warn
A warning message is printed.error
An error message is printed.
The following configuration options match against a warning message generated:
Option | Usage |
---|---|
forced-cleanup-of-active-subsessions |
Normally a warning message will be printed if a Diameter Session is terminated with active subsessions which had previously been created using a MSCC AVP. These warnings may be suppressed. |
termination-of-unknown-subsession |
Normally a warning message is printed if an unknown subsession is terminated. Some Diameter clients choose to terminate subsessions even if previously terminated by the Server. These warnings may be suppressed. |
termination-of-unknown-session |
Normally a warning message is printed if an unknown session is terminated. Some Diameter clients choose to terminate sessions late, not honoring the validity time of the original session. These warnings may be suppressed. |
Message Validation
Validation may be applied per command type:
"validation": {
"commands": [
/* Per command validation */
]
}
Diameter message validation is covered separately in the Diameter Message Validation section.
Application Configuration
Each endpoint requires one or more applications to be defined. The endpoint applications are defined in an
applications
array:
"applications": [
{
"class-path": /* full path */
}
]
The JSLEE Diameter service supports two applications:
- For Diameter Agents, set
class-path
tonz.co.nsquared.slee.diameter.application.agent.Agent
. Agent configuration is covered by the Diameter Agent Documentation. - For Diameter credit-control servers, set
class-path
tonz.co.nsquared.slee.diameter.application.credit_control.Server
. Credit Control configuration is covered by the Credit Control Server Documentation.