Configuring Diameter Sh Client Nodes and Relay Agents

The following sections describe how to configure individual servers to act as Diameter nodes or relays in a WebLogic SIP Server domain:

Overview of Diameter Protocol Configuration

A typical WebLogic SIP Server domain deploys support for the Diameter base protocol and IMS Sh interface provider on all engine tier servers, which each act as Diameter Sh client nodes. SIP Servlets deployed on the engines can use the profile service API to initiate requests for user profile data, or to subscribe to and receive notification of profile data changes. The Sh interface is also used to communicate between multiple IMS Application Servers. Using the Profile Service API (Diameter Sh Interface) in Programming Applications with WebLogic SIP Server describes the API in more detail.

One or more server instances may be also be configured as Diameter relay agents, which route Diameter messages from the client nodes to a configured Home Subscriber Server (HSS) in the network, but do not modify the messages. BEA recommends configuring one or more servers to act as relay agents in a domain. The relays simplify the configuration of Diameter client nodes, and reduce the number of network connections to the HSS. Using at least two relays ensures that a route can be established to an HSS even if one relay agent fails.

Note that relay agent servers do not function as either engine or data tier instances—they should not host applications, store call state data, maintain SIP timers, or even use SIP protocol network resources (sip or sips network channels).

WebLogic SIP Server also provides a simple HSS simulator that you can use for testing Sh client applications. You can configure a WebLogic SIP Server instance to function as an HSS simulator by deploying the appropriate application.

Steps for Configuring Diameter Client Nodes and Relay Agents

To configure Diameter support in a WebLogic SIP Server domain, follow these steps:

Install the WebLogic SIP Server Diameter Domain. Install the Diameter domain, which contains a sample configuration and template Web Applications configured for different Diameter node types.
Create Diameter network channels. Create the network channels necessary to support Diameter over TCP or TLS transports on engine tier servers and relays.
Configure the Diameter Sh client nodes (engine tier servers). Configure the Diameter Sh client application on engine tier servers with the host name, peers, and routes to the relay agents or HSS.
Configure Diameter relay agents (optional). Configure the Diameter relay application on one or more server instances to act as relay agents to an HSS.
Configure an HSS Simulator (optional). Configure a the Diameter relay application on a WebLogic SIP Server instance to function as an HSS simulator for testing or example purposes.

Installing the Diameter Domain

The Configuration Wizard includes a Diameter domain template that creates a domain having four WebLogic SIP Server instances:

You can use the installed Diameter domain as the basis for creating your own domain. Or, you can use the customized Diameter Web Applications as templates for configuring existing WebLogic SIP Server instances to function as HSS client or relay agent nodes. The configuration instructions in the sections that follow assume that you have access to the Diameter domain configuration. Follow these steps to install the domain:

Change to the WLSS_HOME\common directory, where WLSS220 is the directory in which you install WebLogic SIP Server 2.2 (for example, c:\bea\wlss220\common).
Execute the config.cmd or config.sh script to launch the Configuration Wizard.
Select Create a new WebLogic Configuration and click Next.
Select the Diameter WebLogic SIP Server domain and click Next.
Select Express and click Next.
Select the preconfigured server, "myserver" to function as the Administration Server and click Next.
Enter a username and password for the Administrator of the new domain, and click Next.
Select the startup mode and JDKs to use with the new domain, and click Next.
Click Create to create the new domain using the default domain name and domain location (BEA_HOME/user_projects/domains/diameter).
Click Done.

Table 5-1 describes the server configuration installed with the Diameter domain.

Table 5-1 Key Configuration Elements of the Diameter Domain
Server Name	Network Channel Configuration	Deployed Applications	Notes
`myserver`	n/a	n/a	The Administration Server uses no SIP or Diameter network channels and deploys no `sipserver` or Diameter application.
`hssclient`	diameterchannel (UDP/TCP over port 3868) sipchannel (UDP/TCP over port 5060)	`./diameter_hssclient` ./sipserver	The `hssclient` server shows the sample configuration of an engine tier server that functions as a Diameter Sh client node. The server contains network channels supporting both SIP and Diameter traffic. The `diameter_hssclient` Web Application configures the server as an Sh client node, and the `sipserver` implementation application provides SIP container services.
`relay`	diameterchannel (TCP over port 3869)	`./diameter_relay`	The `relay` server shows the sample configuration of a server that functions as a Diameter Sh relay node. The server contains a network channel to support both Diameter traffic. The server does not contain a channel to support SIP traffic, as a relay performs no SIP message processing. The `diameter_relay` Web Application configures the Diameter relay application to connect the `hssclient` and `hss` servers. The `sipserver` EAR is not deployed to the relay as it provides no SIP container functionality.
`hss`	diameterchannel (TCP over port 3870)	`./diameter_hss`	The `hss` server deploys only the HSS simulator application code, and is configured with a Diameter network channel.

Creating Network Channels for the Diameter Protocol

WebLogic SIP Server's Diameter implementation supports the Diameter protocol over two different transport protocols: TCP and TLS. To enable incoming Diameter connections on a server, you must configure a dedicated network channel using the protocol type "diameter" or "diameters" for TCP and TCP/TLS transport, respectively. The provider may automatically upgrade Diameter connections to use TLS as is described in the Diameter specification (RFC 3558).

Servers that use a TCP/TLS channel for Diameter (diameters channels) must also enable two-way SSL.

To configure a TCP or TCP/TLS channel for use with the Diameter provider, follow these steps:

Access the Administration Console for the WebLogic SIP Server domain.
In the left pane, select the name of the server to configure.
In the right pane, select Protocols->Channels to display the configured channels.
Click Configure a new Network Channel in the right pane.
Fill in the new channel fields as follows:

Name: Enter an administrative name for this channel, such as "Diameter TCP/TLS Channel."
Protocol: Select either diameter to support the TCP transport, or diameters to support both TCP and TLS transports.

Note:

If a server configures at least one TLS channel, the server operates in TLS mode and will reject peer connections from nodes that do not support TLS (as indicated in their capabilities exchange).

Listen Address: Enter the IP address or DNS name for this channel. On a multi-homed machine, enter the exact IP address of the interface you want to configure, or a DNS name that maps to the exact IP address.
Listen Port: Enter the port number used to communication via this channel. Diameter nodes conventionally use port 3868 for incoming connections.

Click Create to create the new channel.
Display the advanced configuration items for the newly-created channel by clicking the Show link next to Advanced Options.
Change the Idle Connection Timeout value from the default (65 seconds) to a larger value that will ensure the Diameter connection remains consistently available.

Note:

If you do not change the default value, the Diameter connection will be dropped and recreated every 65 seconds with idle traffic.

Click Apply.

The servers installed with the Diameter domain template include network channel configurations for Diameter over TCP transport. Note that the relays server includes only a diameter channel and not a sip or sips channel. Relay agents should not host SIP Servlets or other applications, therefore no SIP transports should be configured on relay server nodes.

Configuring Two-Way SSL for Diameter TLS Channels

Diameter channels that use TLS (diameters channels) require that you also enable two-way SSL, which is disabled by default. Follow these steps to enable two-way SSL for a server:

Configure basic SSL support, if you have not already done so. See Configuring SSL in the WebLogic Server 8.1 Documentation.
Access the Administration Console for the WebLogic SIP Server domain.
In the left pane, select the name of the server to configure.
Select the Configuration-->Keystores & SSL tab.
Click the Show link under Advanced Options.
Go to the Server attributes section of the window.
Change the Two Way Client Cert Behavior attribute from the default, Client Certs Not Requested (which defines one-way SSL) to one of the remaining options:

Client Certs Requested But Not Enforced—Requires a client to present a certificate. If a certificate is not presented, the SSL connection continues.
Client Certs Requested And Enforced—Requires a client to present a certificate. If a certificate is not presented or if the certificate is not trusted, the SSL connection is terminated.

Click Apply.
Reboot the server.

Configuring Diameter Sh Client Nodes

All engine tier servers that act as Diameter client nodes share the same configuration for the Diameter Sh client application. (Servers that act as Diameter relay agents configure deploy a different Diameter Web Application.) The Sh client application is deployed as a standalone Web Application, and is configured using a diameter.xml configuration file. To enable Sh client support for engine server nodes, you copy the diameter_hssclient Web Application from the Diameter domain you installed using the configuration wizard, and then modify the configuration files to suit your environment. Follow these steps:

Copy the diameter_hssclient directory contents from the Diameter domain you installed into your own domain. For example:

cp -r ~/bea/user_projects/domains/diameter/diameter_hssclient ~/bea/user_projects/domains/replicated

Open the diameter.xml configuration file with a text editor:

emacs ~/bea/user_projects/domains/replicated/diameter_hssclient/WEB-INF/config/diameter.xml

Edit the configuration file to change the following items to match those for your domain:

The host names of any relay agents configured in the domain, supplied as arguments to the Sh application and defined as Diameter peer nodes. If no relay agents are used, all engine tier servers must be added to the list of peers, or dynamic peers must be enabled.
One or more routes to access relay agent nodes (or the HSS) in the domain.

The template diameter.xml file contains sample values for these items. Listing 5-1 below also shows a sample configuration file for an engine tier cluster that accesses an HSS using two relays, with highlighted comments for certain entries. See Using the IMS Sh Interface (Diameter) in Programming Applications with WebLogic SIP Server for more information about elements in the diameter.xml file.

Listing 5-1 diameter.xml Configuration for Sh Client Nodes Using Relay Agents

<?xml version="1.0" encoding="utf-8"?>

<configuration xmlns:xsi= "http://www.w3.org/2001/XMLSchema-instance"

  xsi:noNamespaceSchemaLocation="http://www.bea.com/ns/wlcp/diameter.xsd">

  <!-- Omit the host and realm elements to dynamically assign the hostname

       and domain name of individual engine tier servers. -->

<node>

  <applications>

    <application>

      <auth-application-id>16777217</auth-application-id>

      <vendor-id>10415</vendor-id>

      <!-- Specify the BEA Sh application ID and Diameter vendor ID. -->

      <class-name>com.bea.wcp.diameter.sh.WlssShApplication</class-name>

      <!-- Identify the BEA Sh application provider class name. -->

      <param>

        <name>dest.host</name>

        <value>HSS_hostname</value>

      </param>

      <!-- Include a dest.host param definition only if servers will

           communicate directly to an HSS (static routing), without using

           a relay agent. Omit the dest.host param completely when routing

           through relay agents. -->

      <param>

        <name>dest.realm</name>

        <value>relayorhss.com</value>

      </param>

      <!-- Specify the realm name of relay agent servers or the HSS,

           depending on whether or not the domain uses relay agents. -->

    </application>

  </applications>

  <peers>

    <peer>

      <host>relay1</host>

      <address>relay1host</address>

      <!-- The address element can specify either a DNS name or IP address,

           whereas the host element must specify a diameter host identity.

           The diameter host identity may or may not match the DNS name. -->

      <port>3821</port>

    </peer>

    <peer>

      <host>relay2</host>

      <address>relay2host</address>

      <port>3821</port>

    </peer>

    <!-- Include peer entries for each relay agent server used in the domain.

         If no relay agents are used, include a peer entry for the HSS

         itself, as well as for all other Sh client nodes (all other engine

         tier servers in the domain).

         Alternately, use the allow-dynamic-peers functionality in

         combination with TLS transport to allow peers to be recognized

         automatically. -->

</peers>

  <routes>

    <default-route>

      <action>relay</action>

      <server>relay1</server>

    </default-route>

    <!-- Enter a default route to a selected relay agent. If the domain does

         not use a relay agent, specify a default route to relay messages

         directly to the HSS. -->

    <route>

      <action>relay</action>

      <server>relay2</server>

    </route>

    <!-- Include additional route entries for each relay agent in the

         domain. -->

  </routes>

</node>

</configuration>

Save your changes to the diameter.xml file and exit the text editor.
Start the Administration Server for your domain, and deploy the diameter_hssclient application directory to the engine tier cluster, as in:

java weblogic.Deployer -adminurl t3://localhost:7001 -user weblogic \

   -password weblogic -targets BEA_ENGINE_TIER_CLUST -deploy \

   -source ~/bea/user_projects/domains/replicated/diameter_hssclient

Configuring Diameter Relay Agents (Optional)

Each server instance that acts as a Diameter relay agent must be configured independently (have a dedicated diameter.xml configuration file packaged in a copy of the Diameter Web Application). Relay agents are not required in a Diameter configuration, but BEA recommends using at least two relay agent servers to limit the number of direct connections to the HSS, and to provide multiple routes to the HSS in the event of a failure.

Relay agent nodes route Sh messages between client nodes and the HSS, but they do not modify the messages except as defined in the Diameter Sh specification. Relays always route responses from the HSS back the client node that initiated the message, or the message the response is dropped if that node is unavailable.

Copy the diameter_relay directory contents from the Diameter domain you installed into a new directory in your own domain:

cp -r ~/bea/user_projects/domains/diameter/diameter_relay ~/bea/user_projects/domains/replicated/diameter_relay1

Note that you will need to create and configure a separate "diameter_relay" application directory for each relay in your system.

Open the diameter_relay application's diameter.xml configuration file with a text editor. For example:

emacs ~/bea/user_projects/domains/replicated/diameter_relay1/WEB-INF/config/diameter.xml

Edit the configuration file to change the following items to match those for your domain:

The host and realm name of the relay agent server.
The host and port names of all servers acting as Diameter Sh client nodes, defined as Diameter peer nodes.
A default route to the HSS configured in the network.

The template diameter.xml file contains sample values for these items. Listing 5-2 below also shows a sample configuration file for a single relay node in the example two-relay system described in Example Domain Configuration.

Listing 5-2 diameter.xml Configuration for a Diameter Relay Agent Server

<?xml version="1.0" encoding="utf-8"?>

<configuration xmlns:xsi= "http://www.w3.org/2001/XMLSchema-instance"

  xsi:noNamespaceSchemaLocation="http://www.bea.com/ns/wlcp/diameter.xsd">

  <host>relay1</host>

  <realm>bea.com</realm>

  <!-- Specify the host and realm name for this relay agent. -->

<node>

  <applications>

    <application>

      <auth-application-id>-1</auth-application-id>

      <class-name>com.bea.wcp.diameter.relay.RelayApplication</class-name>

      <!-- Identify the BEA relay application class name. -->

    </application>

  </applications>

  <peers>

    <!-- Define peer connection information for each Sh client, or use the

         allow-dynamic-peers functionality in combination with TLS

         transport to allow peers to be recognized automatically. -->

    <peer>

      <host>engine1</host>

      <address>engine1host</address>

      <port>3821</port>

    </peer>

    <peer>

      <host>engine2</host>

      <address>engine2host</address>

      <port>3821</port>

    </peer>

    <peer>

      <host>engine3</host>

      <address>engine3host</address>

      <port>3821</port>

    </peer>

    <peer>

      <host>relay2</host>

      <address>relay2host</address>

      <port>3821</port>

    </peer>

    <peer>

      <host>hss</host>

      <address>hsshost</address>

      <port>3821</port>

    </peer>

    <!-- Include peer entries for each engine tier server (each Diameter

         client node), additional relay agents, and for the HSS itself. -->

  </peers>

  <routes>

    <default-route>

      <action>relay</action>

      <server>hss</server>

    </default-route>

    <!-- Enter a default route for this agent to relay messages

         to the HSS. -->

  </routes>

</node>

</configuration>

Save your changes to the diameter.xml file and exit the text editor.
Start the Administration Server for your domain, and deploy the correct "diameter_relay" application directory to the corresponding WebLogic SIP Server instance. Use either the Administration Console or the weblogic.Deployer utility, as in:

java weblogic.Deployer -adminurl t3://localhost:7001 -user weblogic \

   -password weblogic -deploy -targets Relay1 \

   -source ~/bea/user_projects/domains/replicated/diameter_relay1

Example Domain Configuration

This section describes a sample WebLogic SIP Server configuration that provides basic Diameter Sh protocol capabilities. The layout of the sample domain includes the following:

The listings that follow show the contents of diameter.xml files used in to configure the sample domain.

Configuring an HSS Simulator

The Diameter domain template installs a diameter_hss Web Application that you can deploy to a server instance in order to simulate an HSS in your domain. This is provided for testing or development purposes only, and is not meant as a substitute for a production HSS.

Copy the diameter_hss directory contents from the Diameter domain you installed into a new directory in your own domain:

cp -r ~/bea/user_projects/domains/diameter/diameter_hss ~/bea/user_projects/domains/replicated/

Open the diameter_hss application's diameter.xml configuration file with a text editor. For example:

emacs ~/bea/user_projects/domains/replicated/diameter_hss/WEB-INF/config/diameter.xml

Edit the configuration file to change the following items to match those for your domain:

The host and realm name of the HSS.
The host and port names of all servers acting as Diameter relay nodes (or as Diameter Sh client nodes if your system uses no relays), defined as Diameter peer nodes.
A default route to relay to the HSS server itself.

The template diameter.xml file contains sample values for a domain having a single relay. Listing 5-6 below shows the contents of this file.

Listing 5-6 diameter.xml Configuration for an HSS Simulator

<?xml version="1.0" encoding="utf-8"?>

<configuration xmlns:xsi= "http://www.w3.org/2001/XMLSchema-instance"

  xsi:noNamespaceSchemaLocation="http://www.bea.com/ns/wlcp/diameter.xsd">

<node>

  <host>hss</host>

  <realm>hss.com</realm>

  <applications>

    <application>

      <auth-application-id>16777217</auth-application-id>

      <vendor-id>10415</vendor-id>

      <class-name>com.bea.wcp.diameter.sh.HssSimulator</class-name>

    </application>

  </applications>

  <peers>

    <peer>

      <host>relay</host>

      <address>localhost</address>

      <port>3869</port>

    </peer>

  </peers>

 <routes>

   <default-route>

     <action>relay</action>

     <server>relay</server>

   </default-route>

 </routes>

</node>

</configuration>