18 Diameter Configuration Reference (diameter.xml)

This chapter describes the Oracle Communications WebRTC Session Controller Diameter configuration file, diameter.xml.

Overview of diameter.xml

The diameter.xml file configures attributes of a Diameter node, such as:

  • The host identity of the Diameter node

  • The Diameter applications that are deployed on the node

  • Connection information for Diameter peer nodes

  • Routing information and default routes for handling Diameter messages.

The Diameter protocol implementation reads the configuration file at start time. diameter.xml is stored in the domain_home/config/custom subdirectory where domain_home is the root directory of the WebRTC Session Controller domain.

Graphical Representation

Figure 18-1 shows the element hierarchy of the diameter.xml file.

Figure 18-1 Element Hierarchy of diameter.xml

Description of Figure 18-1 follows
Description of "Figure 18-1 Element Hierarchy of diameter.xml"

Editing diameter.xml

WARNING:

You should never move, modify, or delete the diameter.xml file during normal operations.

Oracle recommends using the Administration Console to modify diameter.xml indirectly, rather than editing the manually with a text editor. Using the Administration Console ensures that the diameter.xml document always contains valid XML.

You may need to manually view or edit diameter.xml to troubleshoot problem configurations, repair corrupted files, or to roll out custom Diameter node configurations to a large number of machines when installing or upgrading WebRTC Session Controller. When you manually edit diameter.xml, you must restart Diameter nodes to apply your changes.

Caution:

Always use the Diameter node in the Administration Console or the WLST utility, as described in Chapter 6, "Configuring WebRTC Session Controller Container Properties" to make changes to a running WebRTC Session Controller deployment.

Steps for Editing diameter.xml

If you need to modify diameter.xml on a production system, follow these steps:

  1. Use a text editor to open the WSC_home/config/custom/diameter.xml file, where WSC_home is the root directory of the WebRTC Session Controller domain.

  2. Modify the diameter.xml file as necessary. See "XML Element Description" for a full description of the XML elements.

  3. Restart or start servers to have your changes take effect.

  4. Test the updated system to validate the configuration.

XML Schema

The XML schema file (wcp-diameter.xsd) is bundled within the wlssdiameter.jar library, installed in WL_home/wlserver/sip/server/lib, where WL_home is the path to the directory where WebLogic Server is installed.

Example diameter.xml File

See Chapter 5, "Configuring WebRTC Session Controller Diameter Rx to PCRF Integration" for examples of diameter.xml configuration files.

XML Element Description

The following sections describe each XML element in diameter.xml.

configuration

The top level configuration element contains the entire diameter node configuration.

target

Specifies one or more target WebRTC Session Controller instances to which the node configuration is applied. The target servers must be defined in the config.xml file for your domain.

host

Specifies the host identity for this Diameter node. If no host element is specified, the identity is taken from the local server's host name. The host identity may or may not match the DNS name.

Note:

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

realm

Specifies the realm name for which this Diameter node has responsibility. You can run multiple Diameter nodes on a single host using different realms and listen port numbers. The 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.

If you omit the realm element, the realm named is derived using the domain name portion of the host name, if the host name is fully-qualified (for example, host@oracle.com).

address

Specifies the listen address for this Diameter node, using either the DNS name or IP address. If you do not specify an address, the node uses 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 element with an explicit DNS name or IP address to avoid configuration errors.

port

Specifies the TCP or TLS listen port for this Diameter node. The default port is 3868.

tls-enabled

This element is used only for standalone node operation to advertise TLS capabilities.

WebRTC Session Controller ignores the tls-enabled element for nodes running within a server instance. Instead, TLS transport is reported as enabled if the server instance has configured a Network Channel having TLS support (a diameters channel). See "Creating TCP, TLS, and SCTP Network Channels for the Diameter Protocol".

sctp-enabled

This element is used only for standalone node operation to advertise SCTP capabilities.

WebRTC Session Controller ignores the sctp-enabled element for nodes running within a server instance. Instead, SCTP transport is reported as enabled if the server instance has configured a Network Channel having SCTP support (a diameter-sctp channel). See "Creating TCP, TLS, and SCTP Network Channels for the Diameter Protocol".

debug-enabled

Specifies a boolean value to enable or disable debug message output. Debug messages are disabled by default.

message-debug-enabled

Specifies a boolean value to enable or disable tracing of Diameter messages. This element is disabled by default.

application

Configures a particular Diameter application to run on the selected node. WebRTC Session Controller includes applications to support nodes that act as Diameter Rx clients, Diameter relay agents, or Home Subscriber Servers (HSS). The HSS application is a simulator that is provided only for development or testing purposes.

class-name

Specifies the application class file to load.

param*

Specifies one or more optional parameters to pass to the application class.

name

Specifies the name of the application parameter.

value

Specifies the value of the parameter.

peer-retry-delay

Specifies the number of seconds this node waits between retries to Diameter peers. The default value is 30 seconds.

allow-dynamic-peers

Specifies a boolean value that enables or disables dynamic peer configuration. 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.

request-timeout

Specifies the number of milliseconds to wait for an answer from a peer before timing out.

watchdog-timeout

Specifies the number of seconds used for the Diameter Tw watchdog timer.

include-origin-state-id

Specifies whether the node should include the origin state AVP in requests and answers.

supported-vendor-id+

Specifies one or more vendor IDs to be added to the Supported-Version-Ids AVP in the capabilities exchange.

peer+

Specifies connection information for an individual Diameter peer. You can choose to configure connection information for individual peer nodes, or allow any node to be dynamically added as a peer. Oracle recommends using dynamic peers only if you are using the TLS transport, because there is no way to filter or restrict hosts from becoming peers when dynamic peers are enabled.

When configuring Sh client nodes, the peers element should contain peer definitions for each Diameter relay agent deployed to your system. If your system does not use relay agents, you must include a peer entry for the Home Subscriber Server (HSS) in the system and for all other engine nodes that act as Sh client nodes.

When configuring Diameter relay agent nodes, the peers element should contain peer entries for all Diameter client nodes that access the peer and the HSS.

host

Specifies the host identity for a Diameter peer.

address

Specifies the listen address for a Diameter peer. If you do not specify an address, the host identity is used.

port

Specifies the TCP or TLS port number for this Diameter peer. The default port is 3868.

protocol

Specifies the protocol used by the peer. This element may be one of tcp or sctp.

route

Defines a realm-based route that this node uses when resolving messages.

When configuring Sh client nodes, you should specify a route to each Diameter relay agent node deployed in the system and a default-route to a selected relay. If your system does not use relay agents, simply configure a single default-route to the HSS.

When configuring Diameter relay agent nodes, specify a single default-route to the HSS.

realm

The target realm used by this route.

application-id

The target application ID for the route.

action

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

  • none

  • local

  • relay

  • proxy

  • redirect

server+

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

default-route

Defines a default route to use when a request cannot be matched to a configured route.

action

Specifies the default routing action for the Diameter node. See "route" for more information.

server+

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.