Relay and Proxy Agents

Introduction

The JSLEE Diameter Agent conforms to RFC6733, relaying, translating, redirecting, and proxying Diameter messages across the JSLEE between Diameter Gateway services running in server and client modes.

Basic Agent Configuration

Basic configuration for a Diameter Agent requires the configuration of a JSLEE Diameter service for incoming Diameter messages, acting as a Diameter Server. The JSLEE server configuration excerpt for this function requires the following setup:

{
  "applications": {
    "diameter-relay": {
      "handler": "nz.co.nsquared.slee.diameter.DiameterVerticle",
      "configuration": {
        "endpoints": [
          {
            "interface": "127.0.0.1",
            "port": 3868,
            "origin-host": "dra.nsquared.io",
            "origin-realm": "nsquared.io",
            "name": "inbound",
            "avp-definitions": [
              "IETF RFC 6733",
              "3GPP TS 32.299"
            ],
            "is-enabled": true,
            "is-server": true,
            "applications": [
              {
                "class-path": "nz.co.nsquared.slee.diameter.application.agent.Agent",
                "routing": [
                  {
                    "condition": "true",
                    "destination": "diameter-relay/jslee",
                    "avps": {
                      "Destination-Realm": "nsquared.io,
                      "Destination-Host": "ocs1"
                    }
                  }
                ]
              }
            ]
          }
        ]
      }
    }
  }
}

The key configuration of the Diameter server for Agent functionality are:

Config Section Description
applications.class-path A Diameter application, within the endpoint of the server configuration, must be configured with the class-path of nz.co.nsquared.slee.diameter.application.agent.Agent.
avp-definitions The Diameter Agent must be configured to support the AVP definitions of at least RFC6733.
caches An array of one or more cache definitions, to be used in routing lookups by the Diameter Agent.
is-server The Diameter Agent may be flagged as a Diameter server or client
routing One or more mappings defining Diameter routing configuration between JSLEE service/endpoint addresses and Diameter peers (realms and hosts).

Diameter endpoint configuration, including for validation, timeouts, encoding and decoding rules, and basic details such as the Origin-Host may all be configured as covered by the general Diameter configuration documentation.

Agent-Specific Configuration

Extra configuration fields used by the agent include:

Field Type Required? Default Description
verify-proxiable-flag Boolean No False Determine whether the Agent acts strictly and verifies that all proxied messages have the Proxiable flag set to true.

Configuration-Based Routing

The routing section of the configuration determines how a Diameter messages received by the Agent will be routed within the JSLEE. As the Agent is designed to relay & proxy out to another Diameter agent, the prime purpose of each element in the routing array is to determine which Diameter peer to proxy the incoming diameter message through to.

Each of the routes within the routing configuration can also hold a collection of AVPs which are used to update the AVPs on the incoming Diameter message. A routing rule defines:

  1. A condition. A route will be selected based on matching the incoming Diameter message against the selection rule. The simplest condition would be true, to capture all messages.
  2. Defining the internal JSLEE service destination for further processing.

Note that if the Diameter session has previously been seen and successfully routed, and session-based routing is enabled then the Diameter message will not be processed using the routing rules. Instead, the Agent will re-route the message along the same message path as earlier messages in the session have been.

A minimal JSON to relay all messages received to a target service might be:

{
  "condition": "true",
  "destination": "diameter-relay/outbound",
  "avps": {
    "Destination-Realm": "nsquared.io",
    "Destination-Host": "ocs1.nsquared.io"
  }
}

This relay would pass all messages through, adding (or replacing) Diameter AVPs as appropriate (specifically the Destination-Realm and Destination-Host fields). The relay agent will perform logging and EDR generation, from the input source to the output connection.

A specific diameter realm and host delivery can be targeted by including the destination realm field in the avps collection, as shown in the above configuration extract.

In the relay’s condition field, complex selectors can be defined as JSON configuration, determining whether a relay is to be used or not:

{
  "condition": "getAvp(\"CC-Request-type\") != 3 && getAvp(\"Multiple-Services-Credit-Control\") != null",
  "destination": "any:diameter-relay/ocs1"
}

The JSON definition of the conditional logic is consistent with the JSLEE Translator Service, the details of which are covered by the expressions documentation.

By default, the relay agent will relay using static configuration without any dynamic lookup.

However, if an AVP value is defined as a JSON hash object, the relay agent will dynamically look up the AVP value based on a cache and key from the incoming message.

The following configuration for example will extract out the Subscription-ID field, and select the destination based on that origin:

{
  // condition and destination defined
  "avps": {
    "Destination-Realm": {
      "cache": "msisdn-lookup",
      "lookup-avp": "Subscription-ID"
    }
  }
}

Routing to a Diameter Service

If a route is to another Diameter service running a Diameter agent, add the is-agent-service flag to the route:

{
   "condition": "true",
   "destination": "diameter-relay/outbound",
   "is-agent-service": true
}

The use of the is-agent-service ensures that Diameter services receiving inbound messages can safely route to outbound Diameter services based on Destination realm/host.

Routing Lookup via Cache

The Diameter relay agent relies on the JSLEE Cache subsystem for the management of cache data. See the JSLEE Cache Management for detailed information on the configuration and management of the lookup cache.

Each endpoint Agent can have it’s own cache definition, defined using the caches configuration option. Shared caches can be defined by using the JSLEE __include mechanism for defining caches once, and including them in each endpoint that requires them.

Custom Routing and Proxy Functions

Where the built-in routing and proxy functionality is insufficient, Diameter messages can be routed to custom logic running in the script engine. The JSLEE script engine is capable of manipulating Diameter messages in code to achieve unique deployment-specific functionality, spec’ed to customer requirements. Diameter-specific script engine functionality is covered in more detail in the message generation chapter of this documentation.