Section 3.118. <ServerDIAMETER>

3.118. <ServerDIAMETER>

This clause tells Radiator to act as a Diameter to RADIUS gateway.

Diameter is an AAA protocol described in RFC 6733 (and others). It provides for TCPIP or SCTP transport and TLS encryption. It makes specific provision for carrying RADIUS compatible requests and defines Diameter to RADIUS gateways. ServerDIAMETER implements such a Diameter to RADIUS gateway.

Incoming Diameter requests are converted as far as possible into RADIUS requests and then dispatched internally within Radiator. A Realm or Handler can be configured to handle the request either locally or proxy it (as a RADIUS request) to another RADIUS server. RADIUS replies are sent back to the originating Diameter peer. Handlers may use the Client-Identifier to match requests received by a particular <ServerDIAMETER> clause.

By default, <ServerDIAMETER> listens for connections from Diameter peers on TCP port 3868. By default it does not require TLS encryption of the Diameter connection. <ServerDIAMETER> never contacts a Diameter peer by itself: it always acts only as a Diameter server.

By default, <ServerDIAMETER> uses a hardwired internal dictionary to translate Diameter requests into readable parameters. You can use the global configuration parameter DiameterDictionaryFile to alter the hardwired internal dictionary.

<ServerDIAMETER> supports TLS. For more information about TLS parameters, see Section 3.11. TLS configuration.

3.118.1. Port

This optional parameter specifies which network port ServerDIAMETER will listen on for connections from Diameter peers. Defaults to 3868, the official IANA port number for Diameter. May be a numeric port number or symbolic port/service name.

3.118.2. BindAddress

This optional parameter specifies one or more network interface addresses to listen for incoming connections. It is only useful if you are running Radiator on a multi-homed host (a host that has more than one network address). The default value is the global BindAddress, which defaults to 0.0.0.0. It listens to all networks connected to the host. For more information, see Section 3.7. Global parameters.

Using this parameter, you can run multiple instances of Radiator on the one computer, where each instance listens to connections directed to a different host address. BindAddress can include special formatting characters, and multiple comma separated IPv4 and IPv6 addresses.

When SCTP multihoming is supported, all addresses defined with BindAddress must be either IPv4 or IPv6 addresses. Radiator binds all addresses to one listen socket instead of creating multiple listen sockets.

Here is an example of using BindAddress:

# Only listen on one IPv4 address and the IPv6 loopback
BindAddress 203.63.154.1, ::1

3.118.3. 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 connecting Diameter peers.

Protocol sctp

Tip

On modern Linux hosts, SCTP support is in a loadable module, and can be enabled with:

modprobe sctp

3.118.4. ReadTimeout

This optional parameter specifies the maximum time to wait for incoming Diameter connections to complete their initial handshaking. Defaults to 10 seconds. If a Diameter CER message is not received from the peer by ServerDIAMETER within this time period, the connection will be shut down.

3.118.5. OriginHost

This parameter specifies the name that <ServerDIAMETER> uses to identify itself to any connecting Diameter peers. It is sent to the peer in the Diameter CER message. It is not optional and must be specified in the <ServerDIAMETER> clause. Diameter peers may use OriginHost to determine whether they have connected to the correct peer, so it may be critical that it be configured correctly. Special formatting characters are supported.

3.118.6. OriginRealm

This parameter specifies the name of the user Realm that <ServerDIAMETER> is willing to handle. It is sent to connecting Diameter peers in the CER message, and the peer uses it to determine which requests are routed to this <ServerDIAMETER>. It is not optional an must be specified in the <ServerDIAMETER> clause. Special formatting characters are supported.

3.118.7. ProductName

This optional parameter is used to identify the product name of this Diameter peer. It is sent to connecting Diameter peers in the CER message. It defaults to 'Radiator'.

3.118.8. AddToRequest

This optional parameter is used to add extra RADIUS attributes to the RADIUS request generated from each incoming Diameter request. It can be used to tag requests arriving from ServerDIAMETER for special handling within Radiator or in remote RADIUS servers.

AddToRequest NAS-Identifier=DIAMETER

3.118.9. DefaultRealm

This optional parameter can be used to specify a default realm to use for received Diameter requests that have a user name that does not include a realm. If the incoming user name does not have a realm (i.e. there is no @something following the user name) and if DefaultRealm is specified, the User-Name in the resulting RADIUS request will have @defaultrealm appended to it. The realm can then be used to trigger a specific <Realm> or <Handler> clause. This is useful if you operate a number of Diameter peers for different customer groups and where some or all of your customers log in without specifying a realm.

# Realmless logins to this NAS will be treated
# as if they are for realm open.com.au
<ServerDIAMETER>
      OriginHost ....
      DefaultRealm open.com.au
</ServerDIAMETER>
<Realm open.com.au>
      .....
</Realm>

3.118.10. PreHandlerHook

This optional parameter allows you to define a Perl function that is called during packet processing. It can be configured within several types of clauses for which its functionality is slightly different:

Client clause
PreHandlerHook is called for each request after per-Client user name rewriting and duplicate rejection, and before the request is passed to a Realm or Handler clause.
AuthBy clause
The functionality depends on the used EAP authentication type:
- PEAP, EAP-TTLS, EAP-FAST
  PreHandlerHook specifies a Perl hook to be called before the inner request is re-dispatched to a matching Realm or Handler.
- LEAP
  If EAP_LEAP_MSCHAP_Convert flag is set, PreHandlerHook specifies a Perl hook to be called before the converted request is re-dispatched to a matching Realm or Handler.
- EAP-MSCHAPv2
  If EAP_PEAP_MSCHAP_Convert flag is set, PreHandlerHook specifies a Perl hook to be called before the converted request is re-dispatched to a matching Realm or Handler.
- EAP-GTC
  If EAP_GTC_PAP_Convert flag is set, PreHandlerHook specifies a Perl hook to be called before the converted request is re-dispatched to a matching Realm or Handler.
AuthBy DYNAUTH clause
PreHandlerHook is called for each request created by the clause before the request is passed to a Realm or Handler clause.
ServerRADSEC clause
PreHandlerHook is called for each request after global and per-ServerRADSEC user name rewriting and before the request is passed to a Realm or Handler clause.
ServerDIAMETER clause
PreHandlerHook is called for each request received by ServerDIAMETER before the request is passed to a Realm or Handler clause.
ServerTACACSPLUS clause
PreHandlerHook is called for each request before it is passed to a Realm or Handler clause. If a Client is found for the request, Client's PrehandlerHook is run before ServerTACASPLUS's PreHandlerHook. Global and per-Client user name rewriting and other processing is done before the hooks are run.

A reference to the request is passed as the only argument.

The hook code is compiled by Perl when Radiator starts up. Compilation errors in your hook code are reported to the log file at start-up time. Runtime errors in your hook are also reported to the log file when your hook executes. Multiline hooks with trailing backslashes (\) are parsed by Radiator into one long line. Therefore, do not use trailing comments in your hook.

PreHandlerHook 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. Here is an example of using PreHandlerHook:

# Fake a new attribute into the request
PreHandlerHook sub { ${$_[0]}->add_attr('test-attr', \
      'test-value');}

3.118.11. 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.118.12. ConvertCommand

This optional parameter defines a conversion from Diameter Command Code to RADIUS Code. Currently the only conversion available is converting STR to Accounting-Request with Acct-Status-Type set to Stop. By default no optional conversions are done. Any unknown ConvertCommand conversions are logged, and later ignored, when this module is loaded.

# Specify one ConvertCommand for each conversion
ConvertCommand STR,Accounting-Request

3.118.13. 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.118.14. 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.118.15. MaxBufferSize

This optional advanced parameter specifies the maximum number of octets that are output and input buffered by Radiator's Stream modules. This advanced parameter usually does not need adjusting.

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

3.118.17. StreamMaxClients

This optional parameter specifies the maximum number of accepted connections for each listen socket. This parameter is not set by default. When the parameter is set to zero or unset, no restrictions apply. This parameter is available for all StreamServer based modules, such as <ServerDIAMETER> and <ServerRADSEC>.

With server farm, see FarmSize, this parameter allows distributing all incoming connections equally between worker processes. For example, if the number of connections is known not to exceed 10, a farm of 12 workers will have 2 spare workers with each of the 10 remaining workers handling one connection each.

Note

Currently this parameter is used as follows: All values larger than 0 are treated as 1.

# Allow one connection for each listen socket
StreamMaxClients 1

3.118.18. PacketTrace

This optional flag forces all packets that pass through this module to be logged at trace level 5 until they have been completely processed. This is useful for logging packets that pass through this clause in more detail than other clauses during testing or debugging. The packet tracing stays in effect until it passes through another clause with PacketTrace set off or 0.

PacketTrace is available for the following clauses:

Client
Handler
Realm
AuthBy
ServerDIAMETER
ServerRADSEC
ServerTACACSPLUS

Here is an example of using PacketTrace:

# Debug any packets that pass through here
PacketTrace

3.118.19. 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.118.20. 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.118.21. Clients

This optional parameter specifies a list of IP addresses that connections will be accepted from. You can specify one or more comma or space separated IP addresses on each Client line. You can specify multiple Client parameters. Only exact matches are supported at present. The default is to accept connections from any and all clients.

If Clients is specified and a client attempts to connect from an IP address that is not named, Radiator will log a WARNING level message then reject and close the connection.

# Only accept connections from some addresses
Clients 127.0.0.1, 203.63.154.29
Clients 203.63.154.27