Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

Navigation  Back up to About Overview 
  
[+] Expand All
[-] Collapse All

Directed Realm Configuration (.dir) File

A directed realm specifies target methods for directed authentication and directed accounting. Its realm configuration file is called RealmName.dir. By default, a sample .dir file (example.dir) is installed with Steel-Belted Radius Carrier.

The directed authentication feature permits the server to bypass its Authentication Methods list and map an incoming RADIUS request to one or more specific authentication methods. Steel-Belted Radius Carrier chooses the destination method based on routing information found in the request packet. The destination methods may be any authentication methods already configured on the local Steel-Belted Radius Carrier server, regardless of how they were configured; for example, a method may have been configured using Web GUI, the LDAP configuration interface, or an .aut configuration file.

If no directed authentication method is configured, every request percolates through the same Authentication Methods list, as defined in the authentication methods listed in the Authentication Methods page in Web GUI. This behavior may or may not be ideal for every customer. Directed authentication lets you tailor an Authentication Methods list to a customer’s needs.

Directed accounting is also possible. The destination accounting method may be the Steel-Belted Radius Carrier accounting log, an external database configured using an .acc file, or a distinct accounting log file that contains entries only for this customer.

To activate these features, you must create RealmName.dir files, place them in the Steel-Belted Radius Carrier directory, and list them in the [Directed] section of proxy.ini. Subsequently, any requests that arrive addressed to one of these realm names are processed on the local server using the instructions you provided in proxy.ini and the corresponding RealmName.dir file.

After you edit a RealmName.dir file, you must apply your changes. If you have added or changed:

  • Any directed accounting methods, you must stop and restart the server to load your new configuration.
  • Directed authentication methods in which external database (SQL or LDAP) authentication is used, you must stop and restart the server to load your new configuration.
  • Directed authentication methods in which local or pass-through (Native, UNIX, or Host) authentication is used, 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

    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.

    Note: If you edit radius.ini while configuring a realm, you must restart Steel-Belted Radius Carrier to load your new configuration.

[Auth] Section

Directed authentication is enabled in a realm by setting the Enable parameter in the [Auth] section (Table 106) of the corresponding RealmName.dir file, where RealmName is the name of the realm. The syntax is:

[Auth]
Enable = 1
StripRealm = 1
UseMasterDictionary = yes

Table 106: RealmName.dir [Auth] Syntax

Parameter

Function

Enable

  • If set to 1 in the [Auth] section of a RealmName.dir file, the directed authentication realm called RealmName is enabled.
  • If set to 0, the realm is disabled.

By enabling a directed authentication realm, you make it possible for Steel-Belted Radius Carrier to override the Authentication Methods list on the local server by providing an alternate list - for requests addressed to this realm only. Details of this list are provided in the [AuthMethods] section of the same RealmName.dir file.

StripRealm

  • If set to 1, Steel-Belted Radius Carrier strips the realm name from the username before attempting to authenticate the user's request.
  • If set to 0, realm name stripping is disabled.

Note: For directed realms, realm name is enabled (StripRealm = 1) by default. If you want to disable it, you must explicitly set StripRealm to 0.

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.

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.

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.

[AuthMethods] Section

If directed authentication is enabled, the [AuthMethods] section of a RealmName.dir file lists one or more authentication methods to be used.

The syntax is:

[AuthMethods]DescriptionDescription...

where Description is the official name of an authentication method configured on the Steel-Belted Radius Carrier server. For example:

[AuthMethods]
Native User
UNIX User
UNIX Group
<InitializationString=SQL>
<InitializationString=LDAP>

If you want your [AuthMethods] section to reference an external authentication method, a Description string must match the names of that method. If you want your [AuthMethods] section to reference an external database, enter the InitializationString value from the [Bootstrap] section of the corresponding .aut file.

Note: There is no interaction between the settings in the Authentication Methods page and in RealmName.dir files, or between different RealmName.dir files. For example, if you disable the UNIX User method in the Authentication Methods page while it is enabled in a RealmName.dir file, it remains enabled in RealmName.dir.

[Acct] Section

Directed accounting is enabled in a realm by setting the Enable parameter in the [Acct] section (Table 107) of the corresponding RealmName.dir file, where RealmName is the name of the realm. The syntax is:

[Acct]
Enable = 1
StripRealm = 0
RecordLocally = 0
UseMasterDictionary = yes

Table 107: RealmName.dir [Acct] Syntax

Parameter

Function

Enable

  • If set to 1 in the [Acct] section of a RealmName.dir file, the directed accounting realm called RealmName is enabled.
  • If set to 0, the realm is disabled.

By enabling a directed accounting realm, you make it possible for Steel-Belted Radius Carrier to override the normally configured accounting methods on the local server by providing an alternate list - for requests addressed to this realm only. Details of this list are provided in the [AcctMethods] section of the same RealmName.dir file.

Default value is 0.

RecordLocally

  • If set to 1, Steel-Belted Radius Carrier writes accounting records to its main accounting log file in addition to the accounting destinations specified in [AcctMethods].
  • If set to 0, this feature is disabled.

Default value is 0.

StaticAcctRealms

If a value 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

  • If set to 1, Steel-Belted Radius Carrier strips the realm name from the username before attempting to authenticate the user's request.
  • If set to 0, realm name stripping is disabled.

Note: For directed realms, username stripping is enabled (StripRealm = 1) by default. If you want to disable it, you must explicitly set StripRealm to 0.

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.

[AcctMethods] Section

If directed accounting is enabled, the [AcctMethods] section of a RealmName.dir file lists one or more accounting methods to be used. The syntax is:

[AcctMethods]DescriptionDescription...

where Description is the official name of a directed accounting method configured in the proxy.ini file.

[Called-Station-ID] Section

The [Called-Station-ID] section of a RealmName.dir file allows Steel-Belted Radius Carrier to select a realm to be used for directed authentication and accounting based on DNIS information supplied in an incoming RADIUS packet. The [CalledStationID] section lists each DNIS string that identifies the realm. If this string is found in the CalledStationId attribute of an incoming request, the directed authentication and accounting rules found in the corresponding RealmName.dir file are applied to the request.

The syntax is:

[Called-Station-ID]String.String...

where String is a DNIS string.

[ModifyUser] Section

The [ModifyUser] section (Table 108) of a realm directed 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.

Table 108: RealmName.dir [ModifyUser] Syntax

Parameter

Function

AddPrefix=prefix

AddSuffix=suffix

These parameters define the User-Name prefix and suffix.

Modified: 2017-03-07