Proxy RADIUS Configuration (.pro) File

For each proxy realm that you want to configure on the Steel-Belted Radius Carrier server, you must create a file called RealmName.pro, where RealmName is the name of the realm, and you must add this RealmName to the [Realms] section of the proxy.ini file.

Note: If you create or edit a RealmName.pro file, you can apply your configuration changes dynamically, without stopping the server. Issue the SIGHUP (1) signal to the Steel-Belted Radius Carrier process. #./sbrd hup After you do this, Steel-Belted Radius Carrier re-reads proxy.ini, filter.ini, and all .pro and .dir files in the server directory, and resets its realm configuration accordingly. If you edit radius.ini while configuring a realm, you must stop and restart Steel-Belted Radius Carrier to load your new configuration.

[Auth] Section

The [Auth] section (Table 97) of a RealmName.pro file configures authentication for the proxy realm. The key parameters in these sections are:

• TargetsSection, which names the target selection strategy you want to use.
• FilterIn and FilterOut, which name the attribute or subattribute filters you want applied to request and response packets, respectively.

  Table 97: RealmName.pro [Auth] Syntax

  Parameter	Function
  AvailableAsAuthMethod	If set to yes, allows the proxy realm to be used as an authentication method for a directed realm. If set to no, the proxy realm cannot be used as an authentication method for a directed realm. The default is no.
  Enable	If set to 1, enables forwarding of authentication packets to the realm called RealmName. If set to 0, the realm called RealmName is disabled for authentication. Default value is 0.
  FilterOut=name	The FilterOut=name parameter causes Steel-Belted Radius Carrier to apply the filtering rules found in the [name] section of filter.ini. These rules are applied while Steel-Belted Radius Carrier is processing the incoming RADIUS request packet, and before it directs the packet out to the destination realm. You may also think of this as filtering various attributes and values out of the request before directing it to the realm. Note: The FilterOut setting will be applied only to the realm for which it is configured.
  FilterIn=name	The FilterIn=name parameter causes Steel-Belted Radius Carrier to apply the filtering rules found in the [name] section of filter.ini. These rules are applied after Steel-Belted Radius Carrier has received a response in from the destination realm, and while it is preparing the RADIUS response packet for its client. You may also think of this as filtering various attributes and values in to the response before returning it to the client.
  MessageAuthenticator	If set to 1, a Message-Authenticator is inserted into each request forwarded to any target server in the realm. Default value is 0. Note: Both the proxy and the target RADIUS server require this functionality.
  NumAttempts	The number of times a timeout may occur when attempting to contact servers within the realm, before a failure is declared and the attempts to forward the request are stopped. Default value is 3.
  RequestTimeout=x, y, z	A list of times, in seconds, to wait when attempting to contact a target server before timing out. The first value is the time to wait before the first timeout, and so on. The number of items in the list should not exceed the NumAttempts setting. If NumAttempts is greater, the last number listed is reused for subsequent timeouts. Default value is 5. Note: You can specify RequestTimeout or RequestTimeoutMills, but not both.
  RequestTimeoutMills=x, y, z	A list of times, in milliseconds, to wait when attempting to contact a target server before timing out. The first value is the time to wait before the first timeout, and so on. The number of items in the list should not exceed the NumAttempts setting. If NumAttempts is greater, the last number listed is reused for subsequent timeouts. Note: You can specify RequestTimeout or RequestTimeoutMills, but not both.
  RoundRobin	Specifies the number of target servers that are participating in round-robin load balancing. The count begins from the top of the list in the [name] section identified by TargetsSection. Other listed targets are used only after the round-robin targets fail for a particular request. Default value is 0.
  StripRealm	If set to 1, strip the realm name from the username before forwarding. If set to 0, name stripping is disabled. Note: For proxy realms, realm name stripping is disabled (StripRealm = 0) by default. If you want to enable it, you must explicitly set StripRealm to 1. The default value is different for directed realm.
  TargetsSection=name	name identifies a section called [name] that appears elsewhere in the .pro file. This section lists all the targets in a proxy realm. When it receives a request for this proxy realm, Steel-Belted Radius Carrier selects a target from this list. Having the TargetsSection setting available in the [Auth] and [Acct] sections permits you to name different target selection parameters for proxy RADIUS authentication and accounting. Default value of name is AuthTargets, indicating the name of the section is [AuthTargets]. Note: When you configure the .pro file, you must ensure at least one system is referenced in the TargetsSection.
  UseMasterDictionary	If set to yes, inbound proxy responses for this realm use the master Steel-Belted Radius Carrier dictionary when authentication attributes are filtered in. If set to no, proxy responses for this realm use the client-specific dictionary when authentication attributes are filtered in. Default value is yes. The default value is the global setting configured in the UseMasterDictionary parameter in the proxy.ini file. Note: This value overrides the global setting configured in the UseMasterDictionary parameter in the proxy.ini file.

[Acct] Section

The [Acct] section (Table 98) of a RealmName.pro file configures accounting. The key parameters in these sections are:

• TargetsSection, which names the target selection strategy you want to use.
• FilterIn and FilterOut, which name the attribute or subattribute filters you want applied to request and response packets, respectively.

  Table 98: RealmName.pro [Acct] Syntax

  Parameter	Function
  Enable	If set to 1, enables forwarding of accounting packets to the realm called RealmName. If set to 0, the realm called RealmName is disabled for accounting. Default value is 0.
  Block	If set to 0, the Steel-Belted Radius Carrier server sends an accounting acknowledgement immediately (for example, after Steel-Belted Radius Carrier records an accounting message). If set to 1, the Steel-Belted Radius Carrier server waits for a response from the target realm before sending an accounting acknowledgement. Default value is 1. Note: Set the Block parameter to 0 if your network access server is not able to deal with long acknowledgment delays to accounting requests gracefully. To enable parallel proxy for this realm, set the Block parameter to 0.
  FilterOut=name	The FilterOut=name parameter causes Steel-Belted Radius Carrier to apply the filtering rules found in the [name] section of filter.ini. These rules are applied while Steel-Belted Radius Carrier is processing the incoming RADIUS request packet, and before it directs the packet out to the destination realm. You may also think of this as filtering various attributes and values out of the request before directing it to the realm. Note: The FilterOut setting will be applied only to the realm for which it is configured.
  FilterIn=name	The FilterIn=name parameter causes Steel-Belted Radius Carrier to apply the filtering rules found in the [name] section of filter.ini. These rules are applied after Steel-Belted Radius Carrier has received a response in from the destination realm, and while it is preparing the RADIUS response packet for its client. You may also think of this as filtering various attributes and values in to the response before returning it to the client.
  NumAttempts	Specifies the number of times a timeout may occur when attempting to contact servers within the realm, before a failure is declared and the attempts are stopped. Default value is 3.
  RecordLocally	If set to 1, log the packet locally before forwarding. If set to 0, forward the packet and do not log locally. Default value is 0.
  RequestTimeout=x, y, z	A list of times, in seconds, to wait when attempting to contact a target server before timing out. The first value is the time to wait before the first timeout, and so on. The number of items in the list should not exceed the NumAttempts setting. If NumAttempts is greater, the last number listed is reused for subsequent timeouts. Default is 5 seconds. Note: You can specify RequestTimeout or RequestTimeoutMills, but not both.
  RequestTimeoutMills=x, y, z	A list of times, in milliseconds, to wait when attempting to contact a target server before timing out. The first value is the time to wait before the first timeout, and so on. The number of items in the list should not exceed the NumAttempts setting. If NumAttempts is greater, the last number listed is reused for subsequent timeouts. Note: You can specify RequestTimeout or RequestTimeoutMills, but not both.
  RoundRobin	Specifies the number of target servers that are participating in load balancing. The count begins from the top of the list in the [name] section identified by TargetsSection. Other listed targets are only used after the round-robin targets fail for a particular request. Default value is 0.
  SendAckOnProxyFailure	Specifies whether or not the Steel-Belted Radius Carrier server sends an accounting acknowledgement to the NAD when a proxy accounting request is not acknowledged. If set to 1, the Steel-Belted Radius Carrier server sends an accounting acknowledgement to the NAD even if the proxy accounting request is not acknowledged. If set to 0, the Steel-Belted Radius Carrier server does not send an accounting acknowledgement to the NAD if the proxy accounting request is not acknowledged. The default value is 1. Note: If the Block parameter is set to 1 and the RecordLocally parameter is set to 0, the Steel-Belted Radius Carrier server does not send an accounting acknowledgement to the NAD regardless of the SendAckOnProxyFailure setting. If the Block parameter is set to 0, the Steel-Belted Radius Carrier server sends an accounting acknowledgement immediately, regardless of the SendAckOnProxyFailure setting.
  StaticAcctRealms	If a setting is supplied for this parameter, accounting packets are forwarded to a list of realms. The setting given must be a section name defined in the proxyrl.ini file that lists the realms to which the accounting packets are forwarded. See Proxyrl.ini File.
  StripRealm=n	If set to 1, strip the realm name from the username before forwarding. If set to 0, name stripping is disabled. Default value is 0. Note: For proxy realms, realm name stripping is disabled (StripRealm = 0) by default. If you want to enable it, you must explicitly set StripRealm to 1.
  SuppressAuxConnectionAcct	Set to 1 to suppress the proxying of per-flow (auxiliary connection) accounting on a per-realm basis. Set to 0 to enable the proxying of per-flow (auxiliary connection) accounting on a per-realm basis. Note: Use caution when enabling this option as per-flow accounting messages may alter the information in the current sessions table (CST).
  TargetsSection=name	name identifies a section called [name] that appears elsewhere in the .pro file. This section lists all the targets in a proxy realm. When it receives a request for this proxy realm, Steel-Belted Radius Carrier selects a target from this list. Having the TargetsSection parameter available in the [Auth] and [Acct] sections permits you to name different target selection parameters for proxy RADIUS authentication and accounting. The default value of name is AcctTargets; in which case the name of the section is [AcctTargets]. Note: When you configure the .pro file, you must ensure at least one system is referenced in the TargetsSection.
  UseMasterDictionary	If set to yes, inbound proxy responses for this realm use the master Steel-Belted Radius Carrier dictionary when accounting attributes are filtered in. If set to no, proxy responses for this realm use the client-specific dictionary when accounting attributes are filtered in. Default value is yes. The default value is the global setting configured in the UseMasterDictionary parameter in the proxy.ini file. Note: This value overrides the global setting configured in the UseMasterDictionary parameter in the proxy.ini file.

[AutoStop] Section

The [AutoStop] section (Table 99) of a realm configuration file permits you to activate the Proxy AutoStop feature. When this feature is enabled, an AutoStop request is automatically recorded and associated with the session in the current sessions database when the initial Accounting-Start message is received. This AutoStop message may be used later to simulate an Accounting-Stop message which is fed back into the request processing engine, causing it to be forwarded to the appropriate realms and for the normal processes of ending the user session to be enacted.

Note: As the AutoStop record is generated when the session begins, it is simply a duplicate of the original Start request and does not have access to information about the lifetime of the user’s actual activity.

Note: AutoStop records are not saved on persistent storage: this means that if Steel-Belted Radius Carrier is restarted, this information is lost and hence Accounting-Stop messages cannot be simulated for these user sessions.

Table 100 lists the parameters in other configuration files you must enable (set to 1) for AutoStop to operate.

[Called-Station-ID] Section

The [Called-Station-ID] section of a RealmName.pro file allows the target realm to be selected based on DNIS. The [CalledStationID] section lists each DNIS string that identifies the realm. If this string is found in the CalledStationId attribute of an incoming RADIUS request, the request is assumed to be addressed to this realm.

The syntax is:

where String is a DNIS string.

For example:

[Called-Station-ID]
8005551212
8005551213
6175551212

You can also use wildcards, as in the following example:

[Called-Station-ID]
800*
508*

[DynAuth] Section

The [DynAuth] section in each realm.pro file controls the dynamic authorization proxy configuration for each proxy realm.

Target Selection Rules

Each [name] section of a RealmName.pro file specifies a set of rules that Steel-Belted Radius Carrier can use to select a target for proxy-forwarding within the proxy realm. Each [name] section consists of a list of target servers. For any particular request, if the first listed server fails to respond (or is presumed down), the other servers are tried in the order listed. A [name] section is activated by referencing it from the [Auth] and [Acct] sections (Table 102).

The full syntax is:

[Auth]

TargetsSection=nameB

[Acct]

TargetsSection=nameA

[nameA]

Server = n

Server = n

.

.

.

[nameB]

where Server is the name of a server configured as a target for standard proxy RADIUS forwarding, and n is explained in the next section.

Server must match a Proxy entry in the Steel-Belted Radius Carrier database. This Proxy entry provides the address and shared secret for the target server. All other settings in the Proxy entry (retry policy, proxy accounting) are overridden by the settings that you configure in the RealmName.pro file.

Note: If your server has multiple interface cards, you may add a parameter referring to the interface to each line to order the outgoing proxy traffic for the realm through a particular interface. See [Interfaces] Section.

Round-Robin Load Balancing

If you have multiple target servers in a realm, you can select whether to use them in round-robin fashion (load balancing), primary/backup fashion, or a combination of both. The value of the RoundRobin entry in the [Auth] or [Acct] section indicates the number of targets that are to be used in round-robin fashion. The count begins from the top of list in the [name] section. Other listed targets are used only if the round-robin targets fail for a particular request. If RoundRobin is 0 or 1, all requests are routed to the first target in the [name] list, assuming that it is up, the others are tried in the order listed.

If RoundRobin is 2 or greater (say, n), each request is routed to a different target server, in rotation among the first n listed targets. Requests are then load- balanced evenly among those targets. For any particular request, if one target fails to respond, other targets are attempted. The round-robin targets are tried first; if they all fail to respond, any additional targets are then tried in the order in which they appear in the list.

In the following example, RoundRobin is 3. Under normal circumstances, requests are balanced in round-robin fashion among the first three targets. The first request goes to Bert; the next goes to Ernie; the next to George; the next to Bert; the next to Ernie; the next to George; and so on. If any of these servers go down at some point, the other two are tried, in list order. The fourth target (Mary) receives requests only when other targets are down.

[Auth]
RoundRobin=3
NumAttempts=8
TargetsSection=Targets

[Targets]
Bert=1
Ernie=1
George=1
Mary=5

Selecting a Backup Server

If RoundRobin is set to 0, Steel-Belted Radius Carrier makes a selection from the other servers in the list only if the primary server is down.

For example:

[Auth]
RoundRobin=0
NumAttempts=8
TargetsSection=Targets

[Targets]
Bert=1
Ernie=1

In this case, Bert is used until there is a problem; then Ernie becomes the server of second choice.

Realm Retry Policy

Each target selection rule in the [name] section permits you to name a target and assign it a numeric value:

[name]

Server = n

Server = n

.

.

.

The n setting indicates the number of times to retry requests to this target server when no response is received within the amount of time set by RequestTimeout in the [Auth] or [Acct] section.

The number of attempts to all servers within the entire realm is given by the NumAttempts value in the [Auth] or [Acct] section. For example, the NumAttempts is 8 and there are three target servers, each with n set to 3:

[Auth]
NumAttempts=8
TargetsSection=Targets

[Targets]
Bert=3
Ernie=3
George=3

All three servers are down when a request comes into the realm. The first target (Bert) is tried 3 times; then the second target (Ernie) is tried 3 times; and the third target (George) is tried 2 times. At this point, the number of tries to all servers in the realm is 8, which equals NumAttempts. Steel-Belted Radius Carrier returns a failure response from the realm.

Note: A third attempt to George will not be made unless you edited the RealmName.pro file, increased NumAttempts to 9, and reloaded Steel-Belted Radius Carrier.

[FastFail] Section

The [FastFail] section (Table 103) of a realm configuration file permits you to fine-tune retry policies for individual realms, and for specific targets within a realm. If you provide a [FastFail] section, the ProxyFastFail parameter in the radius.ini [Configuration] section is ignored.

Table 103: RealmName.pro [FastFail] Syntax

Parameter	Function
MinFailures=x MinSeconds=y	These parameters define a tolerance level for failures to reach a target server within a realm. Failures are judged according to the NumAttempts and RequestTimeout settings that you defined in the [Auth] or [Acct] sections. A target is presumed down and is assigned that statue after x consecutive failures have occurred and at least y seconds have elapsed. After a target is presumed down, Steel-Belted Radius Carrier directs proxy requests to another target in the same realm, if available. It does not wait for responses from the failed target. However, it sends strobe requests periodically to the failed target to detect when that server comes back up. After a response is received to one of these strobe requests, that server is no longer presumed down. You can configure the interval for sending these strobe requests by setting the StrobeInterval parameter. In addition, you can enable or disable the sending of these strobes on a per-realm basis by setting the StrobeEnable parameter.
ResetSeconds=z	After the realm's tolerance level is exceeded, this parameter specifies how long a target may be presumed down. The ResetSeconds value indicates the maximum number of seconds during which a server can be presumed down in the absence of strobe requests. If z seconds elapse with no strobe requests sent to the down server, the server is reset to up. The status of a target that is presumed down is reset to up when one of the following occurs: A response to a strobe request is received from the server. There has been no request sent to the server for z seconds. Default value is 600 seconds.
SendStatusServer	Specifies the type of strobe request sent to verify the status of the target server. If set to 1, a Status-Server type message is sent as a strobe request. If set to 0, current authentication or accounting packet is sent as a strobe request based on the type of original request received. Default value is 0. When you use the RetryCount parameter to time out spooled packets, you need to send Status-Server packets as strobe requests because some RADIUS servers may not acknowledge duplicate packets.
StrobeEnable	Enables strobe requests on a per-realm basis. If strobes are disabled, the target is taken out of fast-fail after ResetSeconds has elapsed. 0=Disabled 1=enabled (default)
StrobeInterval	Specifies the interval (in seconds) in which strobe requests are sent. The default is 1 second.

[ModifyUser] Section

The [ModifyUser] section (Table 104) of a realm configuration file permits you to decorate a realm, where the realm is determined by other means, such as DNIS or attribute mapping.

This is used mainly to enhance directed realms. For example, the following two users are in the database: george@gm and george@ford. Either user can log in as george, because Steel-Belted Radius Carrier determines the realm, for example, by DNIS. Based on the realm, Steel-Belted Radius Carrier appends either @gm or @ford to the username, and then uses the Native User directed method to authenticate.

This methodology can also be used in a double-proxy situation. The first proxy uses DNIS to determine a realm, then decorates the name and forwards it to the next hop server. This second proxy (which may be a legacy RADIUS server that does not understand DNIS) can then handle realms based on the name decoration.

Table 104: RealmName.pro [ModifyUser] Syntax

Parameter	Function
AddPrefix=prefix AddSuffix=suffix	These parameters define the User-Name prefix and suffix.

[SpooledAccounting] Section

Proxy spooling is configured within the [SpooledAccounting] section (Table 105) of a RealmName.pro file.

[SpooledAccounting]
Enable=1
RolloverSeconds=600
RolloverSize=1048576
Directory=./all_acct_data
RetryInterval=60
ShutdownDelay=20
RetryCount=0

Table 105: RealmName.pro [SpooledAccounting] Syntax

Parameter	Function
Directory	Specifies the directory where the spool (.psf) files are stored. The directory must be manually created in the RADIUS service directory. Default is ./RealmName Note: Each realm must have its own directory for spool files. Otherwise, packets for multiple realms are interspersed and a problem in one realm can prevent subsequent packets to other realms from being forwarded.
Enable	If set to 1, proxy spooling is enabled. If set to 0, proxy spooling is disabled. Default value is 0.
RetryCount	Specifies the number of times a proxy request is retransmitted if an acknowledgment from the target system is not received after a successful strobe attempt. If the number of retries is exhausted, the current spooled proxy request is abandoned and the next spooled packet is sent. Default value is 0. Setting RetryCount to 0 disables the timing out of unacknowledged spooled requests. Note: The RetryCount parameter takes effect only when the StrobeEnable parameter is set to 1.
RetryInterval	Specifies the interval in seconds before retrying a proxy request if the target system (the downstream server where accounting data for this realm is sent) is down. Default value is 60.
RolloverSeconds	Specifies the rollover interval in seconds. After the interval elapses, the current spool file is closed and a new one is created. Default value is 600 (10 minutes.)
RolloverSize	Specifies the rollover file size limit in bytes. After the file size exceeds this limit, the current spool file is closed and a new one is created. If both RolloverSeconds and RolloverSize are set, the first parameter that exceeds its limit initiates rollover. Default value is 1,048,576 bytes (1 megabyte).
ShutdownDelay	Specifies the amount of time (given as the number of seconds) before the execution of a shutdown request during which the final undelivered spooled packets in the spool file can be sent to their target. This value should reflect the amount of accounting data normally received for this realm and other network conditions that may have an impact on the delay. If the target system is down when Steel-Belted Radius Carrier shuts down, this setting is not applied, and unspooling terminates immediately (and Steel-Belted Radius Carrier shuts down immediately). Upon restart, unspooling of accounting data restarts from the beginning of the oldest spool file. Default value is 20.

Note: A new log file, in the yyyymmdd_Failed.act format, containing information about records that are abandoned after the configured RetryCount number of retries, is created. This file includes information such as packet code, ID, length, target name, and port.

Note: Do not enable proxy spooling for realms that are not enabled for accounting. Account Spooling guarantees sequential delivery of proxied accounting packets through a single-threaded mechanism. However, the use of Account Spooling can adversely affect performance in systems that may sustain heavy load and high latency, or both of proxy targets.

Retry Sequence

If Steel-Belted Radius Carrier receives an accounting packet for a realm, and the target system is down, Steel-Belted Radius Carrier implements the RealmName .pro retry configuration, as in the following example:

[Acct]
RequestTimeout=5, 3, 5
NumAttempts=3

In this example, Steel-Belted Radius Carrier attempts to proxy forward the accounting packet to the target IP address, as it does in a non-SpooledAccounting scenario. Three attempts are made; the first waits for 5 seconds before timing out, the second 3 seconds, and the third 5 seconds.

If there is still no response from the target after three attempts, the RetryInterval in the [SpooledAccounting] section is applied. If RetryInterval equals 60, then 5 seconds after the last unsuccessful NumAttempts is completed, Steel-Belted Radius Carrier waits another 60 seconds and then attempts the entire retry policy again.

Note: Because Account Spooling guarantees sequential delivery of proxied accounting packets through a single-threaded mechanism, its use can adversely affect performance in systems that may sustain heavy load.

Modified: 2018-01-11