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:

  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 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:

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:

  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.