Section 3.71. <AuthBy RADSEC>

3.71. <AuthBy RADSEC>

<AuthBy RADSEC> proxies RADIUS requests to a <ServerRADSEC> clause on remote Radiator using the RadSec (RFC 6614) secure reliable RADIUS proxying protocol. It can be used instead of

<AuthBy
                     RADIUS>

when proxying across insecure or unreliable networks such as the internet. For more information about the RadSec protocol, see Section 16. RadSec (RFC 6614).

<AuthBy
                     RADSEC>

attempts to establish a RadSec connection to the server Hosts when Radiator start up. If the connection subsequently fails or is disconnected, it will attempt to reestablish the connection at ReconnectTimeout intervals.

<AuthBy RADSEC> can be configured for multiple target hosts by specifying multiple Host clauses inside the <AuthBy RADSEC> clause. Normally when a packet is to forwarded, <AuthBy RADSEC> attempts first to send it to the first Host. If no reply is received from that Host within NoreplyTimeout seconds, it attempts to send the request to the next Host and so on. If no reply is heard from any Host, the NoReplyHook is called.

<AuthBy
                     RADSEC>

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

Failure algorithm

<AuthBy
                     RADSEC>

implements a configurable algorithm to detect failed RadSec hosts, and to temporarily disregard failed hosts. The algorithm uses the MaxFailedRequests, MaxFailedGraceTime, and FailureBackoffTime parameters to customise the operation of the algorithm. For more information, see Section 3.42.15. MaxFailedRequests, Section 3.42.16. MaxFailedGraceTime, and Section 3.42.14. FailureBackoffTime. It also uses KeepaliveTimeout and UseStatusServerForFailureDetect in order to use only Status-Server requests for failure detection, instead of any request. For more information, see Section 3.42.9. KeepaliveTimeout and Section 3.42.13. UseStatusServerForFailureDetect.

<AuthBy
                     RADSEC>

initially assumes that each Host is not failed. After a request is sent to a RadSec server, if no reply is received after the NoreplyTimeout, that request is deemed to have failed for that Host. <AuthBy RADSEC> keeps track of how many consecutive requests failed for each Host since the last time a reply was heard from that Host. If more than MaxFailedRequests consecutive requests are deemed to have failed within MaxFailedGraceTime seconds of that last reply heard from that Host, that Host is deemed to have failed.

When the Host is deemed to be failed, <AuthBy RADSEC> does not attempt to send any requests to it until FailureBackoffTime seconds have elapsed. In the meantime,

<AuthBy
                     RADSEC>

attempts to connect or reconnect to the host according to ReconnectTimeout. It also skips sending requests to that Host, and instead attempts to send to the next Host in its list of Hosts (if any).

The default values for these parameters are:

MaxFailedRequests 1
MaxFailedGraceTime 0
FailureBackoffTime 0

These values mean that by default <AuthBy RADSEC> declares the Host failed after a single packet transmission failure, but that it always tries to transmit the next request to the Host. This means that

<AuthBy
                     RADSEC>

always tries to send every request to the first Host, and if nothing is heard from that Host within NoreplyTimeout, it attempts to send to the next Host.

Tip

Judicious use of these parameters allows you to implement a RadSec Host fallback policy, where if one RadSec Host fails to respond to requests, then it will automatically temporarily fall back to the next RadSec Host and so on.

Certificate validation

When a RadSec Server presents a server certificate to an

<AuthBy
                     RADSEC>

Client, the Client performs a number of checks to validate the server certificate. The server certificate is checked for valid start and end dates, and it also checks the chain of validity back to the issuing Certificate Authority, using the root certificates specified in TLS_CAFile or TLS_CAPath. If TLS_PolicyOID parameter is defined, the OIDs must be present in the certificate path. Also a server certificate is accepted only if at least one of the following conditions are true:

The Host name used to connect to the server matches a subjectAltName with type IPADD (IP Address) or DNS (DNS name) in the certificate. Exact or wild card matches are permitted, so a subjectAltName type DNS of ‘*.xyz.com’ matches for any Host in xyz.com.
If there are no subjectAltNames of type DNS in the certificate, if one of the Subject CN (Common Names) in the certificate matches the Host name used to connect to the RadSec server. Exact or wild card matches are permitted.
The Subject in the certificate matches the pattern specified by the TLS_ExpectedPeerName parameter in this <AuthBy RADSEC> clause.

And

If TLS_SubjectAltNameURI parameter is defined in the <AuthBy RADSEC> clause, the certificate must contain a subjectAltName of type URI that matches the TLS_SubjectAltNameURI regular expression.
If TLS_CertificateFingerprint parameter is defined in the <AuthBy RADSEC> clause, the certificate's fingerprint must match at least one of the TLS_CertificateFingerprint options.

Note that the default TLS_ExpectedPeerName pattern is undefined, which means that by default

<AuthBy
                     RADSEC>

requires that the Host name used to connect to the RadSec server matches the subjectAltName or CN in the Server Certificate.

These certificate validation rules are consistent with RFC 2595.

Important

Normally, an <AuthBy RADSEC> clause completes as soon as the request has been forwarded to the remote RadSec server. It does not wait for a reply before moving on to other AuthBy clauses, or handling new requests. <AuthBy RADSEC> always returns IGNORE for AuthByPolicy.

Gossip support in AuthBy RADSEC

The RadSec Hosts can now distribute information about next hop proxy reachability with Gossip. Instead of the current IP address, the configured host name is used as the key when determining if the current report must be processed.

3.71.1. Host

This parameter specifies the host name or address of a RadSec server (the instance of Radiator with a ServerRADSEC clause) that this <AuthBy RADSEC> is to connect to. The address can be an IPv4 or IPv6 name or address. Multiple Host lines are supported, which is equivalent to specifying multiple <Host> clauses. Special formatting characters are supported.

Here is an example of using Host:

# Example Host lines for IPv4 and IPv6 addresses
Host 203.63.154.1
Host oscar.open.com.au
Host ipv6:your.ipv6.host.com
Host 2001:db8:1500:1::a100
# IPv6 loopback:
Host ::1

3.71.2. Secret

This parameter specifies the shared secret that will be used to encrypt passwords and provide basic RADIUS protocol authentication mechanisms for requests and replies passed over the RadSec connection. It must be the same as the Secret configured into the <ServerRADSEC> this clause connects to. The Secret is used to protect passwords even when TLS is not configured for use. If TLS is used, it is not necessary to change it from the default, since the security of TLS does not depend on the shared secret. For compliance with RFC 6614, the default value is radsec. There usually is no need to change this.

3.71.3. Port

This optional parameter specifies the symbolic service name or port number of the port to connect to on Host. The default value is 2083, the official IANA port number for RadSec. Special formatting characters are supported.

3.71.4. 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.71.5. NoreplyTimeout

If no reply is received to a proxied request within this number of seconds, the request is sent to the next Host in the list (if any). If there are no further Hosts, the NoReplyHook is called for this request. The default value is 5 seconds.

3.71.6. KeepaliveTimeout

This optional integer specifies the maximum time in seconds that a RadSec connection can be idle before a Status-Server request is sent to keep the current TCP connection alive. This helps to keep TCP connections open in the face of "smart" firewalls that might try to close idle connections down. The default value is 0 seconds and keepalives are not used. When UseStatusServerForFailureDetect is enabled, KeepaliveTimeout together with MaxFailedRequests defines the minimum time it takes to notice the next hop has failed.

3.71.7. KeepaliveNoreplyTimeout

This is an optional integer that specifies the waiting time, in seconds, for a Status-Server request. If no reply is received within the time KeepaliveNoreplyTimeout defines, the Status-Server request is marked as lost.

If KeepaliveNoreplyTimeout is not defined, the waiting time value depends on the AuthBy you are using:

<AuthBy RADCSEC>: NoreplyTimeout value is used instead.
<AuthBy RADIUS>: RetryTimeout value is used instead.

It is recommended to have a smaller value for KeepaliveNoreplyTimeout and a larger value for NoreplyTimeout or RetryTimeout. The Status-Server responder is always the next hop host and a reply is received quickly. With a short KeepaliveNoreplyTimeout, a possible failure situation is discovered quickly and the request is rerouted to another server. The final destination of an Access-Request or an Accounting-Request message may be located many hops away and for this reason a long NoreplyTimeout may be needed.

Here is an example of using both KeepaliveNoreplyTimeout and NoreplyTimeout in

<AuthBy
                     RADSEC>

:

<AuthBy RADSEC>
      NoreplyTimeout 10
      KeepaliveNoreplyTimeout 3
</AuthBy>

To use this example with <AuthBy RADIUS>, you must use RetryTimeout instead of NoreplyTimeout.

3.71.8. KeepaliveRequestType

This string defines the type of RADIUS request that is sent as a keep-alive request. Any RADIUS request type is allowed. The default value is Status-Server.

Here is an example of using KeepaliveRequestType with AddToKeepaliveRequest:

# Send Access-Request as keepalive probe
KeepaliveRequestType Access-Request
AddToKeepaliveRequest User-Name=mikem,User-Password=fred

3.71.9. AddToKeepaliveRequest

This string adds attributes to the keep-alive request before sending it to Host. The value is a comma-separated list of attribute value pairs on one line, exactly as for any reply item. Special formatting characters are allowed, for more information, see Section 3.3. Special formatters.

Here is an example of using AddToKeepaliveRequest with KeepaliveRequestType:

# Send Access-Request as keepalive probe
KeepaliveRequestType Access-Request
AddToKeepaliveRequest User-Name=mikem,User-Password=fred

3.71.10. UseStatusServerForFailureDetect

If this optional flag is enabled, use only Status-Server requests (if any) to determine that a target server is failed when there is no reply. If not enabled (the default) use no-reply to any type of request. This parameter uses NoreplyTimeout, MaxFailedRequests, MaxFailedGraceTime, FailureBackoffTime during failure detection.

If you enable this, ensure also KeepaliveTimeout is set to a sensible interval to balance between detecting failures early and loading the target server.

3.71.11. StripFromRequest

Strips the named attributes from the request before forwarding it to any Host. The value is a comma-separated list of attribute names. StripFromRequest removes attributes from the request before AddToRequest adds any to the request. There is no default.

# Remove any NAS-IP-Address,NAS-Port attributes
StripFromRequest NAS-IP-Address,NAS-Port

3.71.12. AddToRequest

Adds attributes to the request before forwarding to any Host. Value is a list of comma separated attribute value pairs all on one line, exactly as for any reply item. StripFromRequest removes attributes from the request before AddToRequest adds any to the request. You can use any of the special % formats in the attribute values. There is no default.

# Append a Filter-ID and host name
AddToRequest Calling-Station-Id=1,Login-IP-Host=%h

3.71.13. AddToRequestIfNotExist

Adds attributes to the request before forwarding to any Host. Unlike AddToRequest, an attribute will only be added if it does not already exist in the request. Value is a list of comma separated attribute value pairs. You can use any of the special % formats in the attribute values. There is no default.

# Possibly add our default Operator-Name
AddToRequestIfNotExist Operator-Name=1example.com

3.71.14. IgnoreReject

This optional parameter causes Radiator to ignore (not send back to the original NAS) any Access-Reject messages received from the remote RadSec server. This is sometimes useful for authenticating from multiple RADIUS servers. However, note that if all the remote RADIUS servers reject the request, then the NAS receives no reply at all.

# If we get a reject from the remote, do not send it to the NAS
IgnoreReject

3.71.15. IgnoreAccountingResponse

This optional flag causes

<AuthBy
                     RADSEC>

to ignore replies to accounting requests, instead of forwarding them back to the originating host. This can be used in conjunction with the AccountingHandled flag in a Handler or Realm to ensure that every proxied accounting request is replied to immediately, and the eventual reply from the remote RADSEC server is dropped. For more information about AccountingHandled flag, see Section 3.31.6. AccountingHandled.

3.71.16. HandleAcctStatusTypes

This optional parameter specifies a list of Acct-Status-Type attribute values that will be processed in Accounting requests. The value is a comma-separated list of valid Acct-Status-Type attribute values including, Start, Stop, Alive, Modem-Start, Modem-Stop, Cancel, Accounting-On and Accounting-Off. See your dictionary for a full list.

If HandleAcctStatusTypes is specified and an Accounting request has an Acct-Status-Type not mentioned in HandleAcctStatusTypes, then the request will be ACCEPTed but not otherwise processed by the enclosing clause. The default is to handle all Acct-Status-Type values.

# Only process Start and Stop requests, ACCEPT and acknowledge everything else
HandleAcctStatusTypes Start,Stop

3.71.17. AcctFailedLogFileName

The name of a files used to log failed Accounting-Request messages in the standard radius accounting log format. If no reply is ever received from any of the remote hosts, the accounting message is logged to the named file. For more information about log file format, see Section 9.5. Accounting log file. If no AcctFailedLogFileName is defined, failed accounting messages are not logged. The default is no logging. The file name can include special formatting characters as described in Section 3.3. Special formatters, which means that, for example, using the %c specifier, you can maintain separate accounting log files for each Client. The AcctFailedLogFileName file is always opened, written and closed for each failure, so you can safely rotate it at any time.

The user name that is recorded in the log file is the rewritten user name when RewriteUsername is enabled.

Tip

You can change the logging format with AcctLogFileFormat.

Tip

You may want to make the filename depend on the date, so you get one missed accounting file per day.

# Log all accounting to a single log file in LogDir
AcctFailedLogFileName %L/misseddetails

3.71.18. AcctLogFileFormat

This optional parameter is used to alter the format of the failed accounting log file from the standard radius format when AcctLogFileFormatHook is not defined. AcctLogFileFormat is a string containing special formatting characters. It specifies the format for each line to be printed to the accounting log file. A new line is automatically appended. It is most useful if you use the %{attribute} style of formatting characters (to print the value of the attributes in the current packet.

AcctLogFileFormat %{Timestamp} %{Acct-Session-Id}\
%{User-Name}

3.71.19. AcctLogFileFormatHook

This specifies an optional Perl hook that is used to alter the format of the failed accounting log file from the standard radius format when defined. The hook must return the formatted accounting record. A new line is automatically appended. By default no hook is defined and AcctLogFileFormat or the default format is used. The hook parameter is the reference to the current request.

3.71.20. ReplyHook

This optional parameter allows you to define a Perl function that is called after a reply is received from a remote RadSec server and before it is relayed back to the original client. The following arguments are passed in the following order:

Reference to the reply received from the remote RadSec server is passed as the first argument
Reference to the reply packet being constructed for return to the NAS is passed as the second argument
Reference to the original request from the NAS is passed as the third argument
Reference to the request that was sent to the remote RadSec server is passed as the fourth argument
Reference to the Radius::AuthRADSEC structure is passed as the fifth argument

The response type can be enforced when needed. For example, when the remote RadSec server has rejected the request, the ReplyHook can do any local processing required for rejects and then change the response type to accept.

# Change RadiusResult in the 3rd argument, the original request
ReplyHook sub { ${$_[2]}->{RadiusResult} = $main::ACCEPT; }

The hook code is compiled by Perl when Radiator starts up. Compilation errors in your hook code will be 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.

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

# Fake a new attribute into the reply going back to the client
ReplyHook sub { ${$_[1]}->add_attr('test-attr', \
      'test-value');}

3.71.21. NoReplyHook

This optional parameter allows you to define a Perl function that is called if no reply is received from any RadSec server. A reference to the original request received from the NAS is passed as the first argument. A reference to the request that was forwarded to the remote RADIUS server is passed as the second argument. A reference to the reply packet being constructed for return to the NAS is passed as the third argument (note that the normal behaviour in case of no reply, is for no reply to be sent to the NAS).

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.

NoReplyHook 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. In particular, you can forward the request to another AuthBy RADSEC clause, allowing you to implement automatic failover of RadSec hosts.

# Call another AuthBy RADSEC if this one fails to respond
NoReplyHook sub { Radius::AuthGeneric::find('RADSEC2')\
      ->handle_request(${$_[0]}, ${$_[2]});}

3.71.22. NoReplyReject

This is an optional flag parameter. When this parameter is set, it forces <AuthBy RADSEC> to return with result REJECT to trigger an Access-Reject when a proxied request times out. This parameter is not set by default.

When NoReplyReject is enabled, the reject reason is set to 'Upstream timeout'.

Tip

NoReplyReject allows rejecting timed out requests without hooks such as NoReplyHook. For more information, see Section 3.71.21. NoReplyHook

3.71.23. Asynchronous

The default behaviour for

<AuthBy
                     RADSEC>

is to return IGNORE as soon as the request has been forwarded to the remote RadSec server. It does not wait for a reply before moving on to other AuthBy classes or handling new requests. You can change this behaviour with the Asynchronous flag.

When you enable the Asynchronous flag, Handler continues to evaluate its AuthBy policy after a reply or timeout from the remote proxy. Other requests are processed while the reply is pending.

For more information about how proxied requests are waited for by <AuthBy RADSEC>, see Section 3.71. <AuthBy RADSEC>.

Here is an example of using Asynchronous:

# Auth to server1 and continue to AuthBy FILE if server 1 accepts.
# Process other requests while the reply from server 1 is pending.
<Handler>
      AuthByPolicy ContinueWhileAccept
      <AuthBy RADSEC>
            # Evaluate the policy when we get a reply or a timeout
            Asynchronous
            Host server1
            # Other parameters
      </AuthBy>
      <AuthBy FILE>
            Filename %D/users
      </AuthBy>
</Handler>

3.71.24. ForwardHook

This is a Perl hook that is called once for each request before the request is forwarded to a remote RADIUS or RadSec server. It allows you to modify the forwarded request without changing the current one. ForwardHook receives the following arguments:

Current request
Forwarded request

Here is an example of using ForwardHook:

ForwardHook sub { my $p = $_[0]; my $fp = $_[1]; \
                  $fp->add_attr('OSC-AVPAIR', 'Added by ForwardHook'); }

3.71.25. NoForwardAuthentication

This parameter stops

<AuthBy
                     RADSEC>

forwarding Authentication-Requests. They are ACCEPTED, but no further action is taken with them. This is different in meaning to IgnoreAuthentication, which IGNOREs them.

# Just ACCEPT Authentication-Requests, do not forward them
NoForwardAuthentication

3.71.26. NoForwardAccounting

This parameter stops

<AuthBy
                     RADSEC>

forwarding Accounting-Requests. They are ACCEPTED, but no further action is taken with them. This is different in meaning to IgnoreAccounting, which IGNOREs them.

# Just ACCEPT Accounting-Requests, do not forward them
NoForwardAccounting

3.71.27. AllowInRequest

This optional parameter specifies a list of attribute names that are permitted in forwarded requests. Attributes whose names do not appear in this list are stripped from the request before forwarding.

# Strip everything except username and password
AllowInRequest User-Name,User-Password

3.71.28. 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.71.29. 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.71.30. 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.71.31. FailureBackoffTime

This is an integer that defines the number of seconds for how long <AuthBy RADSEC> does not attempt to send any requests after host is deemed to be failed. During that time, <AuthBy RADSEC> attempts to connect to another host according to host configuration and to send the requests to the next host in the list of hosts, if there is any.

3.71.32. Protocol

This optional parameter specifies which Stream protocol is used to carry RadSec. Options are tcp for TCP/IP or sctp for SCTP (Stream Control Transmission Protocol). The default value is tcp. Not all hosts are able to support sctp, consult your vendor. The protocol setting must be the same in each RadSec server and client.

Protocol sctp

Tip

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

modprobe sctp

3.71.33. ConnectOnDemand

This optional flag parameter tells Radiator not to connect to the server as soon as possible, but to wait until a message must be sent to that server. After the connection has been established and message has been delivered, the connection remains as long as possible. If the connection is lost for any reason, it is only re-established when and if there is another message to be sent.

3.71.34. Gossip

The Gossip flag parameter enables this AuthBy to send and listen for notifications (aka. gossip) to/from other Radiator servers when any remote Radius server fails to reply. This is disabled by default.

See Section 3.133. <GossipRedis> for more about the Gossip framework and goodies/farmsize.cfg for a configuration sample.

# Use the configured Gossip implementation for notifications
Gossip

3.71.35. NoKeepaliveTimeoutForChildInstances

If this optional flag is enabled, only the first instance of this server farm will send Status-Server requests. Recommended when Gossip is used to distribute reachability information. This is not set by default.

3.71.36. GossipNoReply

If the GossipNoReply flag parameter is set, then a notification is sent when a remote Radius server fails to reply. Radiator server also increases a counter for failed requests when a notification is received. This is enabled by default.

3.71.37. GossipHostDown

If the GossipHostDown flag parameter is set, then a notification is sent when a remote Radius server is marked down. Radiator server also marks the remote Radius server down when a notification is received. This is enabled by default.

3.71.38. GossipHostUp

If the GossipHostUp flag parameter is set, then a notification will be send when a remote Radius server is marked up and alive again. Radiator server also marks the remote Radius server healthy when a notification is received. This is enabled by default.

3.71.39. ProxyAlgorithm

You can specify one or more hosts to connect to. The default proxy algorithm is to attempt to connect to the first listed host. If it does not reply within NoreplyTimeout seconds, Radiator logs a fail-over and attempts to connect the next listed host.

You can change this default proxy algorithm by configuring ProxyAlgorithm. Currently, it supports the following values:

FailOver
EAPBalance
HashBalance
LoadBalance
VolumeBalance
RoundRobin

ProxyAlgorithm is not set by default, which means that FailOver method is used. Format specifiers, such as %{GlobalVar:name}, are evaluated when the configuration is loaded.

Note

LoadBalance and VolumeBalance use BogoMips parameter to determine which target Host to use. For more information, see Section 3.43.1. BogoMips.

3.71.40. HashAttributes

The HashBalance proxy algorithm uses HashAttributes configuration parameter to specify which attributes in the incoming request are used to select the target host. The default value is %{Request:Calling-Station-Id}:%n.

Here is an example of using HashAttributes:

HashAttributes %{Request:NAS-IP-Address}