Diameter Resource Adaptors 4.0.0 :: Diameter Resource Adaptors Guide

The peer and realm tables are specified using XML. Below are DTDs and examples of the Diameter peer and realm tables, with notes on their usage.

Tables

Peer table
Realm table
- Realm table DTD
- Realm table example

Peer table

The Diameter peer table specifies statically configured peers. All outgoing connections to peers must be configured statically. Incoming connections are usually dynamic, but you must configure peers statically if using TLS, because you must supply a valid DN for the peer.

Below are the DTD and examples for client and server.

URIs

The <uri> element is used to configure a peer. For outgoing connections, this information is used to create the connection. For incoming connections, this information is used when allowUnknownPeers is set to false. If allowUnknownPeers is set to true, then peers do not need to be configured, unless they need to use TLS.

Using <uri> vs <hostname>, <port>, and <tls>

The use of <hostname>, <port> and <tls> is deprecated. The <uri> element contains exactly the same information, and it should be used instead.

The format for a URI is specified in RFC6733 section 4.3, "Derived AVP Data Formats".

The equivalent setting for the old <tls> option is determined by the protocol specifier, aaa or aaas. It is critical that the correct protocol is used for both outgoing peer connections and configured peers for incoming connections.

For incoming connections, the port is ignored and to avoid confusion it should not be specified.

Transports

There are two transports supported, TCP and SCTP. To use SCTP, the URI should have a suffix of ;transport=sctp. If no suffix is specified, TCP is used; but ;transport=tcp can still be used for clarity.

For incoming connections, the transport is ignored, but can be set as a hint to a reader of the configuration. The actual transports supported for incoming connections are specified by the transports profile attribute in the configuration profile.

URI examples

aaa://host.example.com

This configures a peer with host name host.example.com. For outgoing connections it will use the default port (3868, the default port when TLS is not used), TCP, and no TLS.

aaa://host.example.com:6666;transport=sctp

This configures a peer with host name host.example.com. For outgoing connections it will use port 6666, SCTP, and no TLS.

aaas://host.example.com:6668;transport=tcp

This configures a peer with host name host.example.com. For outgoing connections it will use port 6668, TCP, and no TLS. If an incoming connection is received from this peer the stack will attempt a TLS handshake. The listen port will not be 6666 but will be whatever is configured in the ListenPort configuration property (link). A <valid-dn> setting must also be supplied.

TLS over SCTP is not supported.

Peer Connection Options

Options can be specified to control low-level TCP or SCTP settings for a peer connection. These can be specified for individual outgoing connections (<option> elements within a <peer>), all outgoing connections (<default-options> element within a <peer-table>) and all incoming connections (<server-default-options> element within a <peer-table>).

The supported options are TCP_NODELAY and SCTP_NODELAY.

The other options defined by the ChannelOption Netty class (and SctpChannelOption for additional SCTP options) are available, however these have not been certified for use by Metaswitch and you should contact your Metaswitch >account management team should you require support for these.

Note that only options whose type is either a Java primitive type, InetSocketAddress, or com.sun.nio.sctp.SctpStandardSocketOptions.InitMaxStreams can be set. The Java type of the option must be specified in the <option-type> element, for example java.lang.Boolean or java.net.InetSocketAddress.

Value format for options with type com.sun.nio.sctp.SctpStandardSocketOptions.InitMaxStreams (that is the SCTP_INIT_MAXSTREAMS option) is maxInStreams,maxOutStreams where both maxInStreams and maxOutStreams are integers between 0 and 65536 inclusive. Note that in this version of Diameter Resource Adaptor the SCTP_INIT_MAXSTREAMS is applied only to outgoing connections.

Peer table DTD

Peer table configuration must conform to this DTD.

<?xml version="1.0" encoding="ISO-8859-1"?>
<!--
  <!DOCTYPE peer-table
    PUBLIC "-//Open Cloud Ltd.//DTD Diameter Peer Table Configuration 1.1.0//EN"
           "http://www.opencloud.com/dtd/diameter-peer-table-1.1.0.dtd">
  -->

<!-- Peer Table may be empty initially, if this is a Diameter server only -->
<!ELEMENT peer-table ( server-child-options?, default-options?, peer* )>
<!ATTLIST peer-table allowUnknownPeers (true|false) "false">

<!ELEMENT server-child-options ( option* )>
<!ELEMENT default-options ( option* )>

<!-- Peer's port and tls only required if connectAtStartup=true -->
<!ELEMENT peer ( uri?, hostname?, port?, address?, tls?, valid-dn?, host-ip-address*, option* )>
<!ATTLIST peer connectAtStartup (true|false) "false">

<!-- Specify peer address as a DiameterURI.  If specified then hostname, port and tls will be ignored
      Using a URI is the only way to specify that sctp transport should be used.
      The connect address can still be optionally overridden using the address element. -->
<!ELEMENT uri (#PCDATA)>

<!-- Optionally override the address to connect to (defaults to host from uri or hostname).  This should not be
     specified if the uri (or hostname) contains a host that can be successfully resolved to an IP address.  -->
<!ELEMENT address (#PCDATA)>

<!-- Specify peer address details separately.  This is deprecated, uri should be used instead. -->
<!ELEMENT hostname (#PCDATA)>  <!-- Deprecated, use uri instead. -->
<!ELEMENT port (#PCDATA)>      <!-- Deprecated, use uri instead. -->
<!ELEMENT tls (#PCDATA)>       <!-- Deprecated, use uri instead. -->

<!ELEMENT valid-dn (#PCDATA)>

<!-- Can be used override the default behaviour of adding a Host-IP-Address AVP
     for every IP address to the CER -->
<!ELEMENT host-ip-address (#PCDATA)>

<!ELEMENT option (option-name, option-type, option-value?)>
<!ELEMENT option-name (#PCDATA)>
<!ELEMENT option-type (#PCDATA)>
<!ELEMENT option-value (#PCDATA)>

Peer table client examples

TCP connections with default options.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE peer-table PUBLIC "-//Open Cloud Ltd.//DTD Diameter Peer Table Configuration 1.1.0//EN"
        "http://www.opencloud.com/dtd/diameter-peer-table-1.1.0.dtd">
<peer-table>
    <default-options>
        <option>
            <option-name>TCP_NODELAY</option-name>
            <option-type>java.lang.Boolean</option-type>
            <option-value>true</option-value>
        </option>
    </default-options>
    <peer connectAtStartup="true">
        <uri>aaa://diameterserver:3868;transport=tcp</uri>
        <address>127.0.0.1</address>
        <valid-dn>CN=diameterserver,OU=example,O=OpenCloud,L=wellington,ST=wellington,C=NZ</valid-dn>
    </peer>
    <peer connectAtStartup="true">
        <uri>aaas://diameterserver2:5868;transport=tcp</uri>
        <address>127.0.0.1</address>
        <valid-dn>CN=diameterserver,OU=example,O=OpenCloud,L=wellington,ST=wellington,C=NZ</valid-dn>
    </peer>
</peer-table>

SCTP connections without default options.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE peer-table PUBLIC "-//Open Cloud Ltd.//DTD Diameter Peer Table Configuration 1.1.0//EN"
        "http://www.opencloud.com/dtd/diameter-peer-table-1.1.0.dtd">
<peer-table>
    <peer connectAtStartup="true">
        <uri>aaa://diameterserver:3868;transport=sctp</uri>
        <address>127.0.0.1</address>  <!-- Used if "diameterserver" is a logical name that does not resolve to an address, useful for testing. -->
    </peer>
    <peer connectAtStartup="true">
        <uri>aaa://ocs-server:3868;transport=sctp</uri>
        <!-- No address element should be used if "ocs-server" is resolvable. -->
        <option>
            <option-name>SCTP_NODELAY</option-name>
            <option-type>java.lang.Boolean</option-type>
            <option-value>false</option-value>
        </option>
    </peer>
</peer-table>

Peer table server example (with TLS)

<?xml version="1.0" encoding="ISO-8859-1"?>

<!DOCTYPE peer-table PUBLIC "-//Open Cloud Ltd.//DTD Diameter Peer Table Configuration 1.1.0//EN" "http://www.opencloud.com/dtd/diameter-peer-table-1.1.0.dtd">

<peer-table allowUnknownPeers="false">
    <!-- If allowUnknownPeers is true, then any peer may connect to this node.
         If allowUnknownPeers is not true, peers connecting to this node as clients must be defined in the Peer Table.
         Since valid DNs must be supplied for incoming TLS connections, it is logical for allowUnknownPeers to be false when using TLS. -->
    <peer>
        <uri>aaas://diameter1.opencloud.com</uri> <!-- Will accept connections from this peer -->
        <valid-dn>CN=diameterclient,OU=example,O=OpenCloud,L=wellington,ST=wellington,C=NZ</valid-dn>
    </peer>
</peer-table>

Peer table server example (with server socket options)

An empty peer table (with allowUnknownPeers="true") can be used to specify channel options that will be set on incoming sockets (children of the acceptor sockets).

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE peer-table PUBLIC "-//Open Cloud Ltd.//DTD Diameter Peer Table Configuration 1.1.0//EN"
        "http://www.opencloud.com/dtd/diameter-peer-table-1.1.0.dtd">
<peer-table allowUnknownPeers="true">
    <server-child-options>
        <!-- Both options can be specified because they will be filtered according to transport of incoming connections. -->
        <option>
            <option-name>TCP_NODELAY</option-name>
            <option-type>java.lang.Boolean</option-type>
            <option-value>true</option-value>
        </option>
        <option>
            <option-name>SCTP_NODELAY</option-name>
            <option-type>java.lang.Boolean</option-type>
            <option-value>true</option-value>
        </option>
    </server-child-options>
</peer-table>

Realm table

This Diameter realm table specifies the routing for the Diameter router. Below are the DTD and an examples.

Realm table DTD

Realm table configuration must conform to this DTD.

<?xml version="1.0" encoding="ISO-8859-1"?>
<!--
 <!DOCTYPE realm-table
 PUBLIC "-//Open Cloud Ltd.//DTD Diameter Realm Table Configuration 1.1//EN"
 "http://www.opencloud.com/dtd/diameter-realm-table-1.1.dtd">
 -->

<!ELEMENT realm-table ( realm*, default-route? )>
<!ELEMENT realm ( realm-name, extension-property*, application-route+ )>
<!ELEMENT realm-name (#PCDATA)>

<!--
The extension-property element defines an extension property that is used to
provide additional RA type specific configuration. The element contains an
optional description of the extension property, its name, Java type and value.
-->
<!ELEMENT extension-property (description?, extension-property-name, extension-property-type, extension-property-value)>

<!--
The description element may contain any descriptive text about the parent
element.
-->
<!ELEMENT description (#PCDATA)>

<!--
The extension-property-name element contains the name of extension property.

Example: <extension-property-name>CreditControlFailureHandling</extension-property-name>
-->
<!ELEMENT extension-property-name (#PCDATA)>

<!--
The extension-property-type element contains a fully-qualified Java class name
of an extension property.
The following are the legal values of extension-property-type: java.lang.Boolean,
java.lang.String, java.lang.Character, java.lang.Integer, java.lang.Double,
java.lang.Byte, java.lang.Short, java.lang.Long, and java.lang.Float.

Example: <extension-property-type>java.lang.String</extension-property-type>
-->
<!ELEMENT extension-property-type (#PCDATA)>

<!--
The extension-property-value element contains the value of an extension property.
The value must be a string that is valid for the constructor of the configuration
property's declared type that takes a single java.lang.String parameter, or for
java.lang.Character configuration properties, a single character.

Example: <extension-property-value>CONTINUE</extension-property-value>
-->
<!ELEMENT extension-property-value (#PCDATA)>



<!ELEMENT application-route ( application, action, transport-failover?, peer-ref+ )>

<!ELEMENT application ( application-id, vendor-id? )>
<!ELEMENT application-id (#PCDATA)>
<!ELEMENT vendor-id (#PCDATA)>

<!-- Must be LOCAL, other actions (RELAY, PROXY, REDIRECT) are not supported yet. -->
<!ELEMENT action (#PCDATA)>

<!--
The transport-failover element selects the expected behaviour in case of transport
failure. If request could be routed to multiple peers (e.g. multiple peer-ref(s)
specified for application-route or default-route) and the selected peer fails,
transport-failover element value defines if request is sent to next peer or
a failure is reported to SBB.

Must be one of BEFORE_FIRST_SEND, RETRANSMIT_ONLY_FIRST, ALWAYS,
default is BEFORE_FIRST_SEND.

BEFORE_FIRST_SEND - select next peer only when request is the first request in a
 session and failure occurred before message was put on the wire.
RETRANSMIT_ONLY_FIRST - in addition to BEFORE_FIRST_SEND behaviour, select next peer
 when the first request in a session timeouts (retransmit to next peer)
ALWAYS - in addition to RETRANSMIT_ONLY_FIRST behaviour, select next peer for any
 (first, subsequent) request in a session (including retransmission of request)

Note:
ALWAYS implicitly requires that session state is replicated by peers acting as
servers in destination realm (or that session state does not require replication).
-->
<!ELEMENT transport-failover (#PCDATA)>

<!-- Refers to a peer in the peer table -->
<!ELEMENT peer-ref ( hostname, metric? )>
<!ELEMENT hostname (#PCDATA)>
<!-- Routing metric, defaults to 0. Higher numbers indicate higher priority -->
<!ELEMENT metric (#PCDATA)>

<!-- If all else fails, look here for a peer to use. -->
<!ELEMENT default-route ( transport-failover?, peer-ref+ )>

Realm table example

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE realm-table PUBLIC "-//Open Cloud Ltd.//DTD Diameter Realm Table Configuration 1.1//EN"
"http://www.opencloud.com/dtd/diameter-realm-table-1.1.dtd">
<realm-table>
    <realm>
       <realm-name>test</realm-name>
       <application-route>
           <application>
               <application-id>4</application-id>
               <vendor-id>0</vendor-id> <!-- optional, default is zero -->
           </application>
           <action>LOCAL</action>
           <peer-ref>
               <hostname>diameterserver</hostname>
               <metric>1</metric>
           </peer-ref>
       </application-route>
    </realm>
    <default-route>
       <peer-ref>
           <hostname>diameterserver</hostname>
           <metric>1</metric>
       </peer-ref>
    </default-route>
</realm-table>

Previous page Next page

Configuring peer and realm tables