Service Configuration

Introduction

Whether a JSLEE Diameter service is deployed with client or server endpoints (or both), is deployed as an Agent for proxy/translation/relay, or as a charging & control endpoint, each endpoint must be configured to manage the network connection between Diameter peers.

Configuration options fall into four general groups:

  1. Configuration required for network connectivity, including message timers.
  2. Configuration required for correctly authenticating and communicating with Diameter peers.
  3. Configuration required for processing and reacting to inbound messages, and for sending outbound messages.
  4. Configuration for determining the type of Diameter application(s) 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 */ }
        ]
      }
  }
}

Each Diameter endpoint may be a Diameter client, or Diameter server. The most basic Diameter endpoint configuration determines this within an endpoints hash object:

{
  "is-server": true
}

The is-server field, when set to true, determines this endpoint as a listening endpoint (and will likely mostly receive Diameter request messages). If set to false, this endpoint connects to a remote server (and will most likely send Diameter request messages).

The Diameter Client page covers the Diameter client logic in further detail.

Inherited Configuration

A Diameter service may 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, e.g. /opt/nsquared/jslee/etc/diameter.json:

{
  "default-endpoint": {
    "avp-definitions": [
      "IETF RFC 6733",
      "3GPP TS 32.299"
    ],
    "is-enabled": true,
    "is-server": false,
    "other-answer-time-limit-ms": 1800,
    "port": "4868"
  }
}

With the main server configuration reusing this configuration as many times as required, e.g. /op/nsquared/jslee/etc/server.json:

{
  "diameter": {
      "handler": "nz.co.nsquared.slee.diameter.DiameterVerticle",
      "instance-count": 1,
      "configuration": {
        "endpoints": [
          {
            "__include": "/opt/nsquared/jslee/etc/diameter.json|default-endpoint",
            "remote-server": "10.42.2.50"
          },
          {
            "__include": "/opt/nsquared/jslee/etc/diameter.json|default-endpoint",
            "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 SMPP servers, and false for Diameter 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-realm 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:

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"
]

Suppressing Warnings

Some message processing scenarios are considered warnings by the JSLEE diameter gateway, yet these scenarios may occur under normal processing in some environments.

It is possible to alter the importance of standard warning messages in the following scenarios by defining JSON configuration as part of a Diameter endpoint:

"log-action-on": {
    "forced-cleanup-of-active-subsessions": "none",
    "termination-of-unknown-subsession": "none"
}

Each option may be one of the following values:

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.

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:

  1. For Diameter Agents, set class-path to nz.co.nsquared.slee.diameter.application.agent.Agent. Agent configuration is covered by the Diameter Agent Documentation.
  2. For Diameter credit-control servers, set class-path to nz.co.nsquared.slee.diameter.application.credit_control.Server. Credit Control configuration is covered by the Credit Control Server Documentation.