6 Configuring Diameter Client Nodes and Relay Agents

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

Section 6.1, "Overview of Diameter Protocol Configuration"
Section 6.2, "Steps for Configuring Diameter Client Nodes and Relay Agents"
Section 6.3, "Installing the Diameter Domain"
Section 6.4, "Enabling the Diameter Console Extension"
Section 6.5, "Creating TCP, TLS, and SCTP Network Channels for the Diameter Protocol"
Section 6.6, "Configuring Diameter Nodes"
Section 6.7, "Example Domain Configuration"
Section 6.8, "Troubleshooting Diameter Configurations"

6.1 Overview of Diameter Protocol Configuration

A typical Oracle WebLogic Server SIP Container 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 Server SIP Container 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 Server SIP Container 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.

6.2 Steps for Configuring Diameter Client Nodes and Relay Agents

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

Install the Oracle WebLogic Server SIP Container 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 Server SIP Container domain, edit the config.xml file to enable the extension.
Create Diameter network channels. Create the network channels necessary to support Diameter over TCP, TLS, or SCTP transports on engine tier servers and relays.
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 Server SIP Container instance.

The sections that follow describe each step in detail. See also the Section 6.7, "Example Domain Configuration".

6.3 Installing the Diameter Domain

The Configuration Wizard includes a Diameter domain template that creates a domain having four Oracle WebLogic Server SIP Container 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 Server SIP Container 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 Server SIP Container (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).
Click Done.

Table 6-2 describes the server configuration installed with the Diameter domain.

Table 6-1 Key Configuration Elements of the Diameter Domain

Server Name	Network Channel Configuration	Diameter Applications	Notes
AdminServer	n/a	n/a	The Administration Server provides no SIP or Diameter protocol functionality.
hssclient	diameter (TCP over port 3868) sip (UDP/TCP over port 5060)	WlssShApplication	The `hssclient` engine functions as a Diameter Sh client node. The server contains network channels supporting both SIP and Diameter traffic. The Diameter node configuration deploys `WlssShApplication` (`com.bea.wcp.diameter.sh.WlssShApplication`) to provide IMS Sh interface functionality for deployed SIP Servlets.
relay	diameter (TCP over port 3869)	RelayApplication	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.

6.4 Enabling the Diameter Console Extension

Oracle WebLogic Server SIP Container 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 6-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.

Example 6-1 config.xml Entries for Enabling the Diameter Console Extension

<custom-resource>
    <name>sipserver</name>
    <target>hssclient</target>
    <descriptor-file-name>custom/sipserver.xml</descriptor-file-name>
    <resource-class>com.bea.wcp.sip.management.descriptor.resource.SipServerResource</resource-class>
    <descriptor-bean-class>com.bea.wcp.sip.management.descriptor.beans.SipServerBean</descriptor-bean-class>
  </custom-resource>
  <custom-resource>
    <name>diameter</name>
    <target>hssclient,relay,hss</target>
    <deployment-order>200</deployment-order>
    <descriptor-file-name>custom/diameter.xml</descriptor-file-name>
    <resource-class>com.bea.wcp.diameter.DiameterResource</resource-class>
    <descriptor-bean-class>com.bea.wcp.diameter.management.descriptor.beans.DiameterBean</descriptor-bean-class>
  </custom-resource>
  <custom-resource>
    <name>ProfileService</name>
    <target>hssclient</target>
    <deployment-order>300</deployment-order>
    <descriptor-file-name>custom/profile.xml</descriptor-file-name>
    <resource-class>com.bea.wcp.profile.descriptor.resource.ProfileServiceResource</resource-class>
    <descriptor-bean-class>com.bea.wcp.profile.descriptor.beans.ProfileServiceBean</descriptor-bean-class>
  </custom-resource>
  <admin-server-name>AdminServer</admin-server-name>
</domain>

6.5 Creating TCP, TLS, and SCTP Network Channels for the Diameter Protocol

The Oracle WebLogic Server SIP Container Diameter implementation supports the Diameter protocol over the TCP, TLS, and SCTP transport protocols. (SCTP transport is provided with certain restrictions as described in Section 6.5.2, "Configuring and Using SCTP for Diameter Messaging".)

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 Server SIP Container 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:

Access the Administration Console for the Oracle WebLogic Server SIP Container domain.
Click Lock & Edit to obtain a configuration lock.
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 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.
Click Next to continue.
For "diameters" channels, select the following two attributes:
- Two Way SSL Enabled: Two-way SSL is required for TLS transport.
- Client Certificate Enforced: Select this attribute to honor available client certificates for secure communication.
Click Finish to create the new 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.

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

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

Oracle WebLogic Server SIP Container supports SCTP for Diameter network traffic, with several limitations:

Only 1 stream per connection is currently supported.
SCTP can be used only for Diameter network traffic; SIP traffic cannot use a configured SCTP channel.
TLS is not supported over SCTP.

In addition, Oracle WebLogic Server SIP Container only supports SCTP channels on the following software platforms:

Red Hat Enterprise Linux 4.0 AS, ES, WS (Kernel 2.6.9, GCC 3.4 or higher) on 32- or 64-bit hardware
Sun Solaris 10 on SPARC

SCTP channels can operate on either IPv4 or IPv6 networks. Section 6.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).

6.6 Configuring Diameter Nodes

The Diameter node configuration for Oracle WebLogic Server SIP Container 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.

6.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 Server SIP Container engine tier instance:

Log in to the Administration Console for the Oracle WebLogic Server SIP Container 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 6-2, then click Finish.

Table 6-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.

6.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 Server SIP Container 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 Server SIP Container 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 Server SIP Container Diameter applications.

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

6.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 6-2 shows a sample node configuration for an Sh client node that uses a relay.

Example 6-2 Sample Diameter Node Configuration with Sh Client Application

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

6.6.2.2 Configuring the Rf Client Application

The Oracle WebLogic Server SIP Container Rf client application enables SIP Servlets to issue offline charging messages using the IMS Rf interface. To configure the Rf application, specify the class com.bea.wcp.diameter.charging.RfApplication. The Rf application accepts the following parameters:

cdf.host specifies the host name of the Charging Data Function (CDF).
cdf.realm specifies the realm of the CDF.

6.6.2.3 Configuring the Ro Client Application

The Oracle WebLogic Server SIP Container Ro client application enables SIP Servlets to issue online charging messages using the IMS Ro interface. To configure the Rf application, specify the class com.bea.wcp.diameter.charging.RoApplication. The Ro application accepts the following parameters:

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.

6.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 Server SIP Container 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:

All other nodes as peers to the relay node.
A default route that specifies the relay action.

Example 6-3 shows the sample diameter.xml configuration for a relay agent node.

Example 6-3 Diameter Relay Node Configuration

<?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>relay</name>
    <target>relay</target>
    <host>relay</host>
    <realm>oracle.com</realm>
    <message-debug-enabled>true</message-debug-enabled>
    <application>
      <name>RelayApplication</name>
      <class-name>com.bea.wcp.diameter.relay.RelayApplication</class-name>
    </application>
    <!-- Define peer connection information for each Diameter node, or use
         the allow-dynamic-peers functionality in combination with TLS 
         transport to allow peers to be recognized automatically. - > 
    <peer>
      <host>hssclient</host>
      <address>localhost</address>
      <port>3868</port>
    </peer>
    <peer>
      <host>hss</host>
      <address>localhost</address>
      <port>3870</port>
    </peer>
    <route>
      <realm>oracle.com</realm>
      <application-id>16777217</application-id>
      <action>relay</action>
      <server>hssclient</server>
    </route>
    <!-- Enter a default route for this agent to relay messages 
         to the HSS. - > 
    <default-route>
      <action>relay</action>
      <server>hss</server>
    </default-route>
  </configuration>
</diameter>

6.6.2.5 Configuring the Sh and Rf Simulator Applications

Oracle WebLogic Server SIP Container 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:

com.bea.wcp.diameter.sh.HssSimulator simulates an HSS in your domain for testing Sh client applications.
com.bea.wcp.diameter.rf.RfSimulator simulates an CDF host for testing Rf client applications

Note:
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 6-2.

Table 6-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.

6.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 6-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 6-4.

Example 6-4 profile.xml sample

<profile-service xmlns="http://www.bea.com/ns/wlcp/wlss/profile/300">
  <mapping>
    <map-by>prefix</map-by>
    <map-by-prefix>
      <provider-prefix-set>
        <name>sh</name>
        <prefix>sh</prefix>
      </provider-prefix-set>
    </map-by-prefix>
  </mapping>
  <provider>
    <name>sh</name>
    <provider-class>com.bea.wcp.profile.ShProviderCached</provider-class>
  </provider>
</profile-service>

6.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 Server SIP Container 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 Server SIP Container 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.
- Watchdog: Indicate whether the peer supports the Diameter Tw watchdog timer interval.
Click Finish to create the new peer entry.
Click Activate Changes to apply the configuration.

6.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 Server SIP Container 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 > Routes tab.
Click New to configure a new Route.
Fill in the fields of the Create a New Route page as follows:
- Name: Enter an administrative name for the route.
- Realm: Enter the target realm for this route.
- Application ID: Enter the target Diameter application ID for this route.
- Action: Select an action that this node performs when using the configured route. The action type may be one of: none, local, relay, proxy, or redirect.
- Server Names: Enter the names of target servers that will use the route.
Click Finish to create the new route entry.
Click Activate Changes to apply the configuration.

See Example 6-3 for an example diameter.xml node configuration containing a route entry.

6.7 Example Domain Configuration

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

Three engine tier servers which host SIP applications and also deploy the Diameter Sh application for accessing user profiles.
Four SIP data tier servers arranged into two partitions with two replicas each.
Two servers that act as Diameter relay agents and forward diameter requests to an HSS.

Figure 6-1 shows the individual servers in the sample configuration.

Figure 6-1 Sample Diameter Domain

Description of "Figure 6-1 Sample Diameter Domain"

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

Example 6-5 diameter.xml Configuration for Sample Engine Tier Cluster (Sh Clients)

<?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>clientnodes</name>
    <target>Engine1</target>
    <target>Engine2</target>
    <target>Engine3</target>
    <realm>sh_wlss.com</realm>
    <application>
      <name>WlssShApplication</name>
      <class-name>com.bea.wcp.diameter.sh.WlssShApplication</class-name>
      <param>
        <name>destination.realm</name>
        <value>relay_wlss.com</value>
      </param>
    </application>
    <peer>
      <host>Relay1</host>
      <address>10.0.1.20</address>
      <port>3821</port>
    </peer>
    <peer>
      <host>Relay2</host>
      <address>10.0.1.21</address>
      <port>3821</port>
    </peer>
    <default-route>
      <action>relay</action>
      <server>Relay1</server>
    </default-route>
    <route>
      <action>relay</action>
      <server>Relay2</server>
    </route>
  </configuration>
</diameter>

Example 6-6 diameter.xml Configuration for Sample Relay Agents

<?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>relaynodes</name>
    <target>Relay1</target>
    <target>Relay2</target>
    <realm>relay_wlss.com</realm>
    <application>
      <name>RelayApplication</name>
      <class-name>com.bea.wcp.diameter.relay.RelayApplication</class-name>
    </application>
    <peer>
      <host>Engine1</host>
      <address>10.0.1.1</address>
      <port>3821</port>
    </peer>
    <peer>
      <host>Engine2</host>
      <address>10.0.1.2</address>
      <port>3821</port>
    </peer>
    <peer>
      <host>Engine3</host>
      <address>10.0.1.3</address>
      <port>3821</port>
    </peer>
    <peer>
      <host>Relay1</host>
      <address>10.0.1.20</address>
      <port>3821</port>
    </peer>
    <peer>
      <host>Relay2</host>
      <address>10.0.1.21</address>
      <port>3821</port>
    </peer>
    <peer>
      <host>hss</host>
      <address>hssserver</address>
      <port>3870</port>
    </peer>
    <default-route>
      <action>relay</action>
      <server>hss</server>
    </default-route>
  </configuration>
</diameter>

6.8 Troubleshooting Diameter Configurations

SIP Servlets deployed on Oracle WebLogic Server SIP Container 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:

Failed to dispatch Sip message to servlet ServletName
java.lang.IllegalArgumentException: No registered provider for protocol: Protocol

The message may indicate that you have not properly configured the associated Diameter application for the protocol. See Section 6.6.2, "Configuring Diameter Applications" for more information.

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 6.6.3, "Configuring Peer Nodes". Keep in mind that Oracle WebLogic Server SIP Container tries only the protocol you specify for the peer configuration (or TCP if you do not specify a protocol).