Section 3.96. <AuthBy DIAMETER>

3.96. <AuthBy DIAMETER>

<AuthBy DIAMETER> converts and forwards all RADIUS authentication and accounting requests to a DIAMETER server. The DIAMETER replies are converted back to RADIUS responses and returned to the requesting client which might be a remote client or this Radiator instance itself. The RADIUS requests may originate from a RADIUS client or they may be converted from TACACS+ or DIAMETER requests.

Diameter peering can be configured with one of these methods:

Directly by an AuthBy DIAMETER with Peer, Port and other parameters. This peering is only usable from within the AuthBy; or
With separate DiaPeerDef clauses that can be shared between multiple AuthBy DIAMETER clauses and other Diameter modules.

See goodies/diameter-authby.cfg for a sample configuration file.

<AuthBy
                     DIAMETER>

understands also the same parameters as <AuthBy xxxxxx>. For more information, see Section 3.32. <AuthBy xxxxxx>. <AuthBy DIAMETER> supports TLS. For more information about TLS parameters, see Section 3.11. TLS configuration.

3.96.1. DiaPeerDef

This parameter defines the Diameter peers to which requests should be sent to. When no DiaPeerDef parameters are set for an AuthBy DIAMETER, Diameter peer connection is established with the parameters configured directly within the AuthBy. DiaPeerDef requires Radiator Service Provider pack. Configuration with DiaPeerDef provides more flexibility, for example, when more than one Diameter peering is needed.

Multiple DiaPeerDef parameters allow using load balancing algorithms to relay to multiple destinations. For more information about available relay options, see file:/data/radiator-reference-manual/source/Configuration/AuthByDIAMETER/RelayAlgorithm_diaclient.dita#RelayAlgorithm.

When one or more DiaPeerDef parameters are set, the following parameters within an AuthBy DIAMETER are ignored: Peer, SCTPPeer, Port, Protocol, AuthApplicationIds, AcctAppliationIds, SupportedVendorIds, LocalAddress, LocalPort, ReconnectTimeout and DisconnectTraceLevel. These parameters are ignored because the AuthBy does not establish a direct peering.

Example

# Relay the requests to peers defined by DiaPeerDef with
# Identifier dra-1 and dra-2 using Session-Id based load balancing.
DiaPeerDef DiaPeerDef-Identifier=dra-1
DiaPeerDef DiaPeerDef-Identifier=dra-2

RelayAlgorithm HashBalance

3.96.2. RelayAlgorithm

This parameter defines the how Diameters requests should be relayed to the peers. At least one DiaPeerDef parameters is required. Some load balancing relay algorithms support multiple destinations.

The following algorithms are currently supported:

FailOver
Messages are sent to one peer only. If the peer becomes unreachable, the next configured peer is used. When a failed peer becomes available, it's used again.
HashBalance
Messages are distributed between all configured peers. If a peer is unavailable, the messages are distributed between the remaining peers. Diameter Session-Id attribute is used as the distribution key.

FailOver can use run-time information about peers for selecting the next hop. For example when a peer advertises its supported applications, Peer-Auth-Application-Id can be used to select peers based on the applications they currently advertise.

HashBalance adds to its targets only those DiaPeerDef clauses that can be found during Radiator startup. Using DiaPeerDef-Identifier is recommended. Here's an example:

Example

# Balance load to multiple Diameter peers based on Diameter Session-Id attribute
RelayAlgorithm HashBalance

# Balance to peers defined with these Identifier values
DiaPeerDef DiaPeerDef-Identifier=aaa-server1
DiaPeerDef DiaPeerDef-Identifier=aaa-server2
DiaPeerDef DiaPeerDef-Identifier=aaa-server3
DiaPeerDef DiaPeerDef-Identifier=aaa-server4

3.96.3. Peer

Name or IP address of DIAMETER peer this

AuthBy
                     DIAMETER

should connect to. When one or more DiaPeerDef parameters are configured, this parameter is ignored.

Note

Currently only one Peer is supported.

3.96.4. SCTPPeer

This parameter specifies one host name or address of an SCTP peer to connect to. When one or more DiaPeerDef parameters are configured, this parameter is ignored within AuthBy DIAMETER. An address can be an IPv4 or IPv6 address. Multiple SCTPPeer parameters are supported. When SCTPPeer is defined, it is used instead of Host or Peer parameters. Special formatting characters are supported. If SCTP multihoming is not supported, connection is attempted to each peer at a time.

When SCTP multihoming is supported, connection is attempted to all peers at once. In this case, all addresses defined with SCTPPeer must be either IPv4 or IPv6 addresses.

Here is an example of using SCTPPeer:

# Peer has multiple IPv6 addresses
SCTPPeer 2001:db8:1500:1::a100
SCTPPeer 2001:db8:1500:2::a100

3.96.5. Port

This optional parameter specifies port name or number of the Diameter peer. Defaults to 3868, the official IANA port number for Diameter. May be a numeric port number or symbolic port/service name. When one or more DiaPeerDef parameters are configured, this parameter is ignored.

3.96.6. DestinationHost

If DestinationHost is unset, no Destination-Host attribute is added to Diameter messages. Setting DestinationHost is optional and there is no default value. Special formatting characters are supported. Formatting is done when the configuration is loaded and <AuthBy DIAMETER> clause is activated.

3.96.7. DestinationRealm

This optional parameter sets the Destination-Realm attribute in the Diameter messages sent to the peer. Destination-Realm is first taken from username's realm part. If there is no realm, then DestinationRealm configuration parameter is used. The default is testdestinationrealm. Special formatting characters are supported. Formatting is done when the configuration is loaded and <AuthBy DIAMETER> clause is activated.

3.96.8. OriginHost

This parameter specifies the name that AuthBy DIAMETER uses to identify itself to a Diameter peer it connects to when no DiaPeerDef parameters are configured.

After the Diameter connection has been established, OriginHost sets the value of the Origin-Realm attribute in the Diameter messages sent to the peer. OriginHost is not optional and must be specified in the AuthBy DIAMETER clause. OriginHost defaults to the hostname of the server Radiator is running on. Special formatting characters are supported. Formatting is done when the configuration is loaded and

AuthBy
                     DIAMETER

clause is activated.

3.96.9. OriginRealm

This parameter sets the value of the Origin-Realm attribute in the Diameter messages sent to the peer. OriginRealm is not optional an must be specified in every AuthBy DIAMETER clause. OriginRealm defaults to testoriginrealm. Special formatting characters are supported. Formatting is done when the configuration is loaded and AuthBy DIAMETER clause is activated.

3.96.10. PostDiaToRadiusConversionHook

This optional parameter allows you to define a Perl function that will be called during packet processing. PostDiaToRadiusConversionHook is called after an incoming Diameter request has been converted to its equivalent RADIUS request, allowing you to alter or add to attribute conversions etc. It is passed references to the incoming Diameter request and the converted RADIUS request.

3.96.11. PostRadiusToDiaConversionHook

This optional parameter allows you to define a Perl function that will be called during packet processing. PostRadiusToDiaConversionHook is called after an RADIUS reply has been converted to its equivalent Diameter reply, prior to being sent back to the Diameter client. It is passed references to the RADIUS reply and the converted Diameter reply.

3.96.12. EAP_ApplicationId

EAP_ApplicationId defines the Diameter message's Application-ID value and Auth-Application-Id AVP value for the converted RADIUS EAP requests. The default is to convert RADIUS EAP authentication to Diameter EAP application. This parameter allows, for example, converting RADIUS EAP-AKA to Diameter 3GPP SWm. EAP_ApplicationId defaults to value Diameter-EAP. For more information, see configuration sample goodies/diameter-authby.cfg

# We can convert EAP-AKA to SWm
EAP_ApplicationId 3GPP SWm

3.96.13. Protocol

This optional parameter specifies which Stream protocol will be used to carry Diameter. Options are 'tcp' for TCP/IP or 'sctp' for SCTP (Stream Control Transmission Protocol). Defaults to 'tcp'. Not all hosts are able to support 'sctp': consult your vendor. The protocol setting must be the same as that being used by the Diameter server.

Protocol sctp

3.96.14. AuthApplicationIds

This optional parameter allows you to define the Auth Application Ids announced in CER. Defaults to '0, 1, 5' (i.e. DIAMETER BASE, NASREQ and Diameter-EAP).

AuthApplicationIds 0, 1

3.96.15. AcctApplicationIds

This optional parameter allows you to define the Acct Application Ids announced in CER. Defaults to ‘3’ (i.e. BASE_ACCOUNTING).

AcctApplicationIds 3

3.96.16. SupportedVendorIds

This optional parameter allows you to define the Supported Vendor Ids announced in CER. There is no default and no Supported-Vendor-Id is announced by default. Keyword "DictVendors" is an alias group for all vendors in the default dictionary and the dictionary file configured with DiameterDictionaryFile.

# Tell the peer we support all the vendors in our
# default and DiameterDictionaryFile dictionaries
SupportedVendorIds DictVendors

3.96.17. LocalAddress and LocalPort

These parameters control the address and optionally the port number used for the client source port, although this is usually not necessary. LocalPort is a string, it can be a port number or name. It binds the local port if LocalAddress is defined. If LocalPort is not specified or if it is set to 0, a port number is allocated in the usual way.

When SCTP multihoming is supported, multiple comma separated addresses can be configured. All addresses defined with LocalAddress must be either IPv4 or IPv6 addresses.

LocalAddress 203.63.154.29
LocalPort 12345

3.96.18. ReconnectTimeout

This optional parameter specifies the number of seconds to wait before attempting to reconnect a failed, dropped or disconnected connection. It also specifies the timeout for the initial connect.

3.96.19. StreamStateChangeHook

This optional parameter allows you to define a Perl function that will be called when a Stream connection state to a peer changes. RadSec, Diameter, TACACS+, HTTP and SIGTRAN clients and servers use Stream connections in Radiator. This is a low layer hook that runs before, for example, RadSec TLS handshake or Diameter Capabilities Exchange messages are exchanged. The following arguments are passed in the following order:

Reference to this Radius::Stream derived type. Examples of derived types are Radius::RadsecHost and Radius::DiameterConnection.
New stream state. One of integer constant values:
- $Radius::Stream::STREAM_STATE::CONNECTED
- $Radius::Stream::STREAM_STATE::DISCONNECTED

StreamStateChangeHook can be an arbitrarily complicated Perl function, that might run external processes, consult databases, change the contents of the current request or many other things. IP address and other specific information is not passed to the hook. Their format and type depends on the derived type. For example, SCTP streams may have multiple source and destination addresses. The following example shows how to log information from the hook no matter what the type of the stream object is.

StreamStateChangeHook sub { \
    my ($self, $new_state) = @_; \
    my $state = ($new_state == $Radius::Stream::STREAM_STATE::CONNECTED) ? \
                  'connected' : 'disconnected'; \
    main::log($main::LOG_INFO, "StreamStateChangeHook: State change to $state"); \
    return; }

3.96.20. DisconnectTraceLevel

This optional parameter specifies log trace level for peer initiated disconnects. The default value is error level 0. When connections are known to be short-lived, a non-default value may be useful. This parameter is available for all Stream based modules, such as <ServerDIAMETER> and <AuthBy RADSEC>.

# Debug logging is enough for peer disconnects
DisconnectTraceLevel 4