10.1 Overview of Diameter Protocol Configuration

A typical Oracle WebLogic Communication Services domain includes support for the Diameter base protocol and one or more IMS Diameter interface applications (Sh, Ro, Rf) deployed to engine tier servers that act as Diameter client nodes. SIP Servlets deployed on the engines can use the available Diameter applications to initiate requests for user profile data, accounting, and credit control, or to subscribe to and receive notification of profile data changes.

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) or other nodes in the network, but do not modify the messages. Oracle 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:

In order to support multiple HSSs, the 3GPP defines the Dh interface to look up the correct HSS. Oracle WebLogic Communication Services does not provide a Dh interface application, and can be configured only with a single HSS.

Note that relay agent servers do not function as either engine or SIP 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).

Oracle WebLogic Communication Services also provides simulator applications for the Sh and Ro protocols. You can use the simulator applications for testing while developing Sh and Ro clients. The simulator applications are not intended for deployment to a production system.

10.2 Steps for Configuring Diameter Client Nodes and Relay Agents

To configure Diameter support in a Oracle WebLogic Communication Services domain, follow these steps:

Install the Oracle WebLogic Communication Services Diameter Domain. Install the Diameter domain, which contains a sample configuration and template applications configured for different Diameter node types. You may use the Diameter domain as a template for your own domain, or to better understand how different Diameter node types are configured.

Enable the Diameter console extension. If you are working with the sample Diameter domain, the Diameter console extension is already enabled. If you are starting with a basic Oracle WebLogic Communication Services domain, edit the config.xml file to enable the extension.

Create and configure the Diameter nodes. Configure the Diameter protocol client applications on engine tier servers with the host name, peers, and routes to relay agents or other network elements, such as an HSS. You can also configure Diameter nodes that operate in standalone mode, without a Oracle WebLogic Communication Services instance.

10.3 Installing the Diameter Domain

The Configuration Wizard includes a Diameter domain template that creates a domain having four Oracle WebLogic Communication Services instances:

An Administration Server (AdminServer)

A Diameter Sh client node (hssclient)

A Diameter relay node (relay)

An HSS simulator (hss)

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 Oracle WebLogic Communication Services 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 WLS_HOME\common\bin directory, where WLS_HOME is the directory in which you installed the Oracle WebLogic Server 10g Release 3 portion Oracle WebLogic Communication Services (for example, c:\bea\wlserver_10.3\common\bin).

Execute the config.cmd or config.sh script to launch the Configuration Wizard.

Select Create a new WebLogic Domain and click Next.

Select Base this domain on an existing template, and click Browse.

Select the diameterdomain.jar template and click OK.

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.

Select No to accept the default template options, and click Next.

Click Create to create the new domain using the default domain name and domain location (/user_projects/domains/diameter).

The relay engine 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 node configuration deploys RelayApplication (com.bea.wcp.diameter.relay.RelayApplication) to provide relay services. The node configuration also defines a realm-based route for relaying messages from the hssclient engine.

hss

diameter (TCP over port 3870)

HssSimulator

The hss engine's Diameter node configuration deploys only the HssSimulator application (com.bea.wcp.diameter.sh.HssSimulator). The server is configured with a Diameter network channel.

10.4 Enabling the Diameter Console Extension

Oracle WebLogic Communication Services provides a console extension to help you create and configure Diameter nodes. The actual configuration generated by the extension is stored in a diameter.xml configuration file, stored in the config/custom subdirectory of the domain directory.

The sample Diameter domain already enables the Diameter console extension. If you are working with a domain that does not enable the extension, edit the config.xml file for the domain to specify the custom resource for the extension. Example 10-1 highlights the config.xml entries necessary to enable the console extension. Use a text editor to add the highlighted lines in the correct location in config.xml.

To enable incoming Diameter connections on a server, you must configure a dedicated network channel of the appropriate protocol type:

"diameter" channels use TCP transport

"diameters" channels use TCP/TLS transport

"diameter-sctp" channels use TCP/SCTP transport.

Servers that use a TCP/TLS channel for Diameter (diameters channels) must also enable two-way SSL. Oracle WebLogic Communication Services may automatically upgrade Diameter TCP connections to use TLS as described in the Diameter specification (RFC 3558).

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

In the right pane, select Protocols > Channels to display the configured channels.

Click New to configure a new channel.

Fill in the fields of the Identity Properties page as follows:

Name: Enter an administrative name for this channel, such as "Diameter TCP/TLS Channel."

Protocol: Select "diameter" to support the TCP transport, "diameters" to support both TCP and TLS transports, or "diameter-sctp" to support TCP transport.

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).

Click Next to continue.

Fill in the fields of the Network Channel Addressing page as follows:

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.

External Listen Port: Re-enter the Listen Port value.

Click Next to continue.

Chose attributes in the Network Channel Properties page as follows:

Enabled: Select this attribute to ensure that the new channel accepts network traffic.

Tunneling Enabled: Un-check this attribute for Diameter channels.

HTTP Enabled for this Protocol: Un-check this attribute for Diameter channels.

Outbound Enabled: Select this attribute to ensure that the node can initiate Diameter messages using the channel.

Select the name of the newly-created channel in the Network Channel table.

Display the advanced configuration items for the newly-created channel by clicking the Advanced link.

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 Save.

Click Activate Changes.

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.

10.5.1 Configuring Two-Way SSL for Diameter TLS Channels

Diameter channels that use TLS (diameters channels) require that you enable two-way SSL, which is disabled by default. Select Two Way Enabled SSL in the steps above to enable two-way SSL.

10.5.2 Configuring and Using SCTP for Diameter Messaging

SCTP is a reliable, message-based transport protocol that is designed for use in telephony networks. SCTP provides several benefits over TCP:

SCTP preserves the internal structure of messages when transmitting data to an endpoint, whereas TCP transmits raw bytes that must be received in order.

SCTP supports multihoming, where each endpoint may have multiple IP addresses. The SCTP protocol can transparently failover to another IP address should a connection fail.

SCTP provides multistreaming capabilities, where multiple streams in a connection transmit data independently of one another.

SCTP channels can operate on either IPv4 or IPv6 networks. Section 10.5 describes how to create a new SCTP channel. To enable multihoming capabilities for an existing SCTP channel, specify the IPv4 address 0.0.0.0 as the listen address for the channel (or use the :: address for IPv6 networks).

10.6 Configuring Diameter Nodes

The Diameter node configuration for Oracle WebLogic Communication Services engines is stored in the diameter.xml configuration file (domain_home/config/custom/diameter.xml). If you want to provide diameter services (client, server, or relay functionality) on an engine tier server, you must create a new node configuration and target the configuration to an existing engine server instance.

Diameter node configurations are divided into several categories:

General configuration defines the host identity and realm for the node, as well as basic connection information and default routing behavior.

Application configuration defines the Diameter application(s) that run on the node, as well as any optional configuration parameters passed to those applications.

Peer configuration defines the other Diameter nodes with which this node operates.

Routes configuration defines realm-based routes that the node can use when resolving messages.

The sections that follow describe how to configure each aspect of a Diameter node.

10.6.1 Creating a New Node Configuration (General Node Configuration)

Follow these steps to create a new Diameter node configuration and target it to an existing Oracle WebLogic Communication Services engine tier instance:

Log in to the Administration Console for the Oracle WebLogic Communication Services domain you want to configure.

Click Lock & Edit to obtain a configuration lock.

Select the Diameter node in the left pane of the Console.

Click New in the right pane to create a new Diameter configuration.

Fill in the fields of the Create a New Configuration page as described in Table 10-2, then click Finish.

Table 10-2 Diameter Node General Configuration Properties

Property Name

Description

Name

Enter the an administrative name for this Diameter node configuration.

Host

Enter the host identity of this Diameter node, or leave the field blank to automatically assign the host name of the target engine tier server as the Diameter node's host identity. Note that the host identity may or may not match the DNS name.

When configuring Diameter support for multiple Sh client nodes, it is best to omit the host element from the diameter.xml file. This enables you to deploy the same Diameter Web Application to all servers in the engine tier cluster, and the host name is dynamically obtained for each server instance.

Realm

Enter the realm name for which this node has responsibility, or leave the field blank to use the domain name portion of the target engine tier server's fully-qualified host name (for example, host@oracle.com).

You can run multiple Diameter nodes on a single host using different realms and listen port numbers.

Note: An HSS, Application Server, and relay agents must all agree on a realm name or names. The realm name for the HSS and Application Server need not match.

Address

Enter the listen address for this Diameter node, using either the DNS name or IP address, or leave the field blank to use the host identity as the listen address.

Note: The host identity may or may not match the DNS name of the Diameter node. Oracle recommends configuring the Address property with an explicit DNS name or IP address to avoid configuration errors.

TLS

Select this option if the Diameter node us configured with support for TLS (diameters network channels). This field is used to advertise TLS capabilities when the node is interrogated by another Diameter node.

Debug

Select this option if you want to enable debug message output. Debug messages are disabled by default.

Message Debug

Select this option if you want to enable tracing for Diameter messages processed by this node. Message tracing is disabled by default.

Dynamic Peers Allowed

Select this option to allow dynamic discovery of Diameter peer nodes. Dynamic peer support is disabled by default. Oracle recommends enabling dynamic peers only when using the TLS transport, because no access control mechanism is available to restrict hosts from becoming peers.

Peer Retry Delay

Enter the amount of time, in seconds, this node waits before retrying a request to a Diameter peer. The default value is 30 seconds.

Request Timeout

Enter the amount of time, in milliseconds, this node waits for an answer message before timing out.

Watchdog Timeout

Enter the number of seconds this node uses for the value of the Diameter Tw watchdog timer interval.

Targets

Enter one or more target engine tier server names. The Diameter node configuration only applies to servers listed in this field.

Default Route Action

Specify an action type that describes the role of this Diameter node when using a default route. The value of this element can be one of the following:

none

local

relay

proxy

redirect

Default Route Servers

Specifies one or more target servers for the default route. Any server you include in this element must also be defined as a peer to this Diameter node, or dynamic peer support must be enabled.

Click Activate Changes to apply the configuration to target servers.

After creating a general node configuration, the configuration name appears in the list of Diameter nodes. You can select the node to configure Diameter applications, peers, and routes, as described in the sections that follow.

10.6.2 Configuring Diameter Applications

Each Diameter node can deploy one or more applications. You configure Diameter applications in the Administration Console using the Configuration > Applications page for a selected Diameter node. Follow these steps:

Log in to the Administration Console for the Oracle WebLogic Communication Services domain you want to configure.

Click Lock & Edit to obtain a configuration lock.

Select the Diameter node in the left pane of the Console.

Select the name of a Diameter node configuration in the right pane of the Console.

Select the Configuration > Applications tab.

Click New to configure a new Diameter application, or select an existing application configuration from the table.

Fill in the application properties as follows:

Application Name: Enter a name for the application configuration.

Class Name: Enter the classname of the application to deploy on this node.

Parameters: Enter optional parameters to pass to the application upon startup.

Click Finish to create the new application configuration.

Click Activate Changes to apply the configuration to the Diameter node.

Oracle WebLogic Communication Services includes several Diameter applications to support clients using the Sh, Rf, and Ro interfaces, Diameter relays, and simulators for the Sh and Ro interfaces. The sections that follow provide more information about configuring these Oracle WebLogic Communication Services Diameter applications.

You can also use the base Diameter API included in Oracle WebLogic Communication Services to create and deploy your own Diameter applications.

10.6.2.1 Configuring the Sh Client Application

The Sh client application is implemented as a provider to the Profile Service API. The application transparently generates and responds to the Diameter command codes defined in the Sh application specification. The Profile Service API enables SIP Servlets to manage user profile data as an XML document using XML Document Object Model (DOM). Subscriptions and notifications for changed profile data are managed by implementing a profile listener interface in a SIP Servlet.

The Diameter nodes on which you deploy the Sh client application should be configured with:

The host names of any relay agents configured in the domain, 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.

To configure the Sh client application, you specify the com.bea.wcp.diameter.sh.WlssShApplication class. WlssShApplication accepts the following parameters:

destination.host configures a static route to the specified host. Include a destination.host param definition only if servers communicate directly to an HSS (static routing), without using a relay agent. Omit the destination.host param completely when routing through relay agents.

destination.realm—configures a static route to the specified realm. Specify the realm name of relay agent servers or the HSS, depending on whether or not the domain uses relay agents.

Example 10-2 shows a sample node configuration for an Sh client node that uses a relay.

<?xml version='1.0' encoding='utf-8'?>
<diameter xmlns="http://www.bea.com/ns/wlcp/diameter/300" xmlns:sec="http://www.bea.com/ns/weblogic/90/security" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:wls="http://www.bea.com/ns/weblogic/90/security/wls">
<configuration>
<name>hssclient</name>
<target>hssclient</target>
<host>hssclient</host>
<realm>oracle.com</realm>
<!-- Omit the host and realm elements to dynamically assign the host name and domain name of individual engine tier servers. - >
<message-debug-enabled>true</message-debug-enabled>
<application>
<name>WlssShApplication</name>
<class-name>com.bea.wcp.diameter.sh.WlssShApplication</class-name>
<param>
<!-- Include a destination.host param definition only if servers will communicate directly to an HSS (static routing), without using a relay agent. Omit the destination.host param completely when routing through relay agents. - >
<!-- Specify the realm name of relay agent servers or the HSS, depending on whether or not the domain uses relay agents. - >
<name>destination.realm</name>
<value>hss.com</value>
</param>
</application>
<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. - >
<host>relay</host>
<address>localhost</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>3869</port>
</peer>
<!-- 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. - >
<default-route>
<action>relay</action>
<server>relay</server>
</default-route>
</configuration>
</diameter>

ocs.host specifies the host identity of the Online Charging Function (OCF). The OCF you specify host must also be configured as the peer for the Diameter node on which the Ro application is deployed.

ocs.realm can be used instead of ocs.host for realm-based routing when using more than one OCF host. The corresponding realm definition must also exist in the Diameter node's configuration.

10.6.2.4 Configuring a Diameter Relay Agent

Relay agents are not required in a Diameter configuration, but Oracle 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.

Note:

You must ensure that relay servers do not also act as Oracle WebLogic Communication Services engine tier servers or SIP data tier servers. This means that the servers should not be configured with "sip" or "sips" network channels.

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.

To configure a Diameter relay agent, simply configure the node to deploy an application with the class com.bea.wcp.diameter.relay.RelayApplication.

The node on which you deploy the relay application should also configure:

10.6.2.5 Configuring the Sh and Rf Simulator Applications

Oracle WebLogic Communication Services contains two simulator applications that you can use in development or testing environments to evaluate Diameter client applications. To configure a simulator application, you simply deploy the corresponding class to a configured Diameter node:

These simulators are provided for testing or development purposes only, and is not meant as a substitute for a production HSS or CDF.

Diameter nodes that deploy simulator applications can be targeted to running engine tier servers, or they may be started as standalone Diameter nodes. When started in standalone mode, simulator applications accept the command-line options described in Table 10-2.

Table 10-3 Command-Line Options for Simulator Applications

Option

Description

-r, -realm realm_name

Specifies the realm name of the Diameter node.

-h, -host host_name

Specifies the host identity of the node.

-a, -address address

Specifies the listen address for this node.

-p, -port port_number

Specifies the listen port number for this node.

-d, -debug

Enables debug output.

-m, -mdebug

Enables Diameter message tracing.

10.6.2.6 Enabling Profile Service (using an Sh backend)

As noted earlier, Sh, Ro, and Rf applications can be configured and used separately, but Sh can take advantage of the Profile Service API. To do so:

Configure ShApplication in diameter.xml (see Example 10-5 for more information).

Add a profile.xml file to domain_home/config/custom/profile.xml. You can either install the Diameter domain as a template and modify the file, or you can manually create profile.xml as shown in Example 10-4.

10.6.3 Configuring Peer Nodes

A Diameter node should define peer connection information for each other Diameter node in the realm, or enable dynamic peers in combination with TLS transport to allow peers to be recognized automatically. You configure Diameter peer nodes in the Administration Console using the Configuration > Peers page for a selected Diameter node. Follow these steps:

Log in to the Administration Console for the Oracle WebLogic Communication Services domain you want to configure.

Click Lock & Edit to obtain a configuration lock.

Select the Diameter node in the left pane of the Console.

Select the name of a Diameter node configuration in the right pane of the Console.

Select the Configuration > Peers tab.

Click New to define a new peer entry.

Fill in the fields of the Create a New Peer page as follows:

Host: Enter the peer node's host identity.

Address: Enter the peer node's address (DNS name or IP address).

Port Number: Enter the listen port number of the peer node.

Protocol: Select the protocol used to communicate with the peer (TCP or SCTP).

Note:

Oracle WebLogic Communication Services attempts to connect to the peer using only the protocol you specify (TCP or SCTP). The other protocol is not used, even if a connection fails using the selected protocol. TCP is used as by default if you do not specify a protocol.

10.6.4 Configuring Routes

Certain Diameter nodes, such as relays, should configure realm-based routes for use when resolving Diameter messages. You configure Diameter routes in the Administration Console using the Configuration > Routes page for a selected Diameter node. Follow these steps:

Log in to the Administration Console for the Oracle WebLogic Communication Services domain you want to configure.

Click Lock & Edit to obtain a configuration lock.

Select the Diameter node in the left pane of the Console.

Select the name of a Diameter node configuration in the right pane of the Console.

Example 10-5 shows the contents of the diameter.xml file used to configure engine tier servers (Sh Clients) in the sample domain. Example 10-6 shows the diameter.xml file used to configure the relay agents.

10.8 Troubleshooting Diameter Configurations

SIP Servlets deployed on Oracle WebLogic Communication Services use the available Diameter applications to initiate requests for user profile data, accounting, and credit control, or to subscribe to and receive notification of profile data changes. If a SIP Servlet performing these requests generates an error similar to:

If you experience problems connecting to a Diameter peer node, verify that you have configured the correct protocol for communicating with the peer in Section 10.6.3, "Configuring Peer Nodes". Keep in mind that Oracle WebLogic Communication Services tries only the protocol you specify for the peer configuration (or TCP if you do not specify a protocol).