Data Accessor Configuration

SQL Data Accessor Configuration

[Bootstrap] Section

The [Bootstrap] section (Table 131) of the SQL data accessor configuration file specifies information that Steel-Belted Radius Carrier uses to load and start the SQL data accessor plug-in.

You can configure more than one SQL data accessor plug-in instance. Each requires its own .gen file in the /radiusdir directory. The [Bootstrap] section of each .gen file must include one of these libraries as the LibraryName entry:

radsql_accessor_ora.so

or
radsql_accessor_jdbc.so

Table 131: [Bootstrap] Syntax

Parameter	Function
LibraryName	LibraryName specifies the name of one SQL data accessor plug-in. It may be: radsql_accessor_ora.so radsql_accessor_jdbc.so
Enable	Specifies whether the SQL data accessor instance is enabled. If set to 0, the SQL data accessor instance is disabled. If set to 1, the SQL data accessor instance is enabled. Default value is 0.

Parameter

Function

LibraryName

LibraryName specifies the name of one SQL data accessor plug-in. It may be:

radsql_accessor_ora.so
radsql_accessor_jdbc.so

Enable

Specifies whether the SQL data accessor instance is enabled.

If set to 0, the SQL data accessor instance is disabled.
If set to 1, the SQL data accessor instance is enabled.

Default value is 0.

[Results] Section

The purpose of the [Results] section is to declare data accessor output container variables and map them to columns in the SQL query result set.

Consider this SELECT statement:

Where user_pwd, attribs, fullname, and user_id are the names of columns in the SQL table, and rasusers is the name of the SQL table itself. The [Results] section maps the output variables to the columns retrieved from the SQL database; for example:

Columns in the SQL query are identified in the [Results] section by number; 1 represents the first column in the SELECT query (from left to right), and if other columns are also references, 2 represents the second, and 3 the third, and so on.

[Settings] Section

The [Settings] section (Table 132) of the SQL data accessor configuration file defines parameters that control the database connection.

Table 132: *.gen [Settings] Syntax

Parameter	Function
ConcurrentTimeout	Specifies the number of seconds a request may wait for execution before it is discarded. Because there may be multiple MaxConcurrent SQL statements executing at one time, new requests must be queued as they arrive until other statements are processed.
Connect	Specifies the string that must be passed to the database client engine to establish a connection to the database. This string has (or refers to) information about the name of the database, its location on the network, the password required to access it, and so forth. The format of the connect string depends on the type of database you use: Oracle: `Connect=<dB_username>/<dB_password>` JDBC: `Connect=DSN=<dsn_name_here> ;UID=<username_for_dB>;PWD= <pas` `sword_for_dB`
ConnectDelimiter	(JDBC only) Specifies the character used to separate fields (DSN, UID, PWD) in the connect string. Default value is a ; (semicolon). If the JDBC connect string requires use of semicolons as part of a field value, you can use this parameter to specify a different delimiter, such as : (colon).
ConnectTimeout	Specifies the number of seconds to wait when attempting to establish the connection to the database before timing out. This value is ignored if the client database engine does not support this feature.
Driver	(JDBC only) Specifies the third-party JDBC driver to load. For example: `Driver=com/provider/jdbc/sqlserver/SQLServerDriver` Note: Third-party JDBC drivers must be installed in the `<JRE-path>/lib/ext` directory. Where, `<JRE-path>` indicates the path where the JRE (that is integrated with SBR Carrier) is installed in your system. Refer to the JDBC driver documentation for information about how to install the JDBC driver and supporting files.
LogLevel	Activates logging for the Data Accessor and sets the rate at which it writes entries to the server log file (.LOG). The LogLevel may be the number 0, 1, or 2, where 0 is the lowest logging level, 1 is intermediate, and 2 is the most verbose. If the LogLevel that you set in the `.gen` file is different than the LogLevel in radius.ini, the radius.ini setting determines the rate of logging.
MaxConcurrent	Specifies the maximum number of instances of a single SQL statement that may be executing at one time.
MaxWaitReconnect	Specifies the maximum number of seconds to wait after successive failures to reconnect after a failure of the database connection. WaitReconnect specifies the time to wait after failure of the database connection. This value is doubled on each failed attempt to reconnect, up to a maximum of MaxWaitReconnect.
ParameterMarker	Specifies the character or sequence of characters used as the parameter marker in a parameterized SQL query. Normally, this is the question mark (?), but this can vary among database vendors.
QueryTimeout	Specifies the number of seconds to wait for a response to a query before timing out. This value is passed to the client database engine, which may or may not implement the feature.
SQL	Specifies the SQL statement used to access and insert information in the database and indicates the names of the variables to create in the input variable container when a SQL statement variable is preceded by a @ sign. The SQL statement may be broken over several lines by ending each line with a backslash. The backslash must be preceded by a space character, and followed by a newline character. The subsequent lines may be indented for better readability. Example: SQL=SELECT password, profile, fullname \FROM usertable \WHERE username = @User-Name
WaitReconnect	Specifies the number of seconds to wait after a failure of the database connection before trying to connect again.

Note

Declare input variables within the SQL query string (SQL parameter) by putting a @ sign before the variable name. This causes Steel-Belted Radius Carrier to create an entry for the variable in the data accessor’s input variable container. This is different from the LDAP data accessor, which uses a separate [Request] section to declare input container variables.

For an example of a SQL accessor configuration, see Example: SQL Data Accessor Configuration File.

[VariableTypes] Section

The [VariableTypes] section of the SQL data accessor configuration file specifies the storage data type for each entry in the input and output variable containers.

Where variable is the name of an input or output container variable and type is the data type specifier, one of string, binary, integer, ipaddress, ipv6address, ipv6prefix, ipv6interface, or date.

For more information about selecting the variable type specifier, see Data Conversion Rules.

LDAP Data Accessor Configuration

[Bootstrap] Section

The [Bootstrap] section of the LDAP data accessor configuration file specifies information that Steel-Belted Radius Carrier uses to load and start the LDAP data accessor plug-in.

You can configure more than one LDAP data accessor plug-in instance. Each requires its own .gen file in the /radiusdir directory. The [Bootstrap] section (Table 133) of each .gen file must provide a LibraryName of ldapaccessor.so.

Table 133: *.gen [Bootstrap] Syntax

Parameter	Function
LibraryName	Specifies the name of the LDAP data accessor plug-in. ldapaccessor.so
Enable	Specifies whether the LDAP data accessor instance is enabled. If set to 0, the LDAP data accessor instance is disabled. If set to 1, the LDAP data accessor instance is enabled. Default value is 0.

Parameter

Function

LibraryName

Specifies the name of the LDAP data accessor plug-in.

ldapaccessor.so

Enable

Specifies whether the LDAP data accessor instance is enabled.

If set to 0, the LDAP data accessor instance is disabled.
If set to 1, the LDAP data accessor instance is enabled.
Default value is 0.

[Attributes/name] Sections

An LDAP search returns all of the attributes associated with an LDAP entry. Many of these attributes may not be relevant to your script. When specifying an LDAP Search for the data accessor, you can provide a list of specific LDAP result attributes to retain by name in the internal variable table. The other attributes are discarded.

You configure [Attributes/name] sections in the LDAP data accessor .gen file to create named lists of LDAP attributes. The syntax is as follows:

where attribute is the name of an LDAP attribute and name is an arbitrary name for the section. You must type the attribute names exactly as they appear in your LDAP database schema. Use one line per attribute. For example:

An [Attributes/name] section is associated with a [Search/name] section using the Attributes parameter. For example:

When the search executes, the selected result attributes are stored by name in the LDAP data accessor internal variable table. If the Attributes parameter is omitted from a [Search/name] section, all of the attributes returned by the LDAP search are stored. Of these attributes, only those referred to in the [Response] section of the .gen file are copied into the output variable container; the rest are discarded after all LDAP searches have completed.

[Response] Section

The [Response] section provides the LDAP data accessor with the names of variables to create in the output variable container. It also indicates to the data accessor which values from the internal variable table to copy to entries in the output variable container after all LDAP repository searches have completed.

The [Response] section syntax is as follows:

Where outvar is the name of a variable in the output variable container and tablevar is the name of an entry in the internal variable table.

[Search/name] Sections

Each [Search/name] section (Table 134) in the LDAP data accessor configuration file specifies the complete details of one LDAP Search request. You can use the same search request on various LDAP repositories because the details of the LDAP server connection are specified separately.

By default, when you execute the search request specified in a [Search/name] section, all the attributes associated with the resulting LDAP record are retained. Use the Attributes parameter to specify a list of specific attributes you want to store in the internal variable table.

Table 134: *.gen [Search/name] Syntax

Parameter	Function
%DN	Specifies an entry in the internal variable in which to place the distinguished name that results from the Search should be placed.
Attributes	Specifies the LDAP attributes relevant to Steel-Belted Radius Carrier, by referencing an [Attributes/name] section elsewhere in the same `.gen` file.
Base	Specifies the distinguished name (DN) of the entry that serves as the starting point for the search. This filter is a template for an LDAP distinguished name string. The filter follows conventional LDAP syntax and may be as simple or as complex as LDAP syntax permits. It may also include replacement variables from the Variable Table. Each replacement variable consists of the variable name enclosed in angle brackets (<>). Upon execution of the LDAP Search request, the value of the variable replaces the variable name.
OnFound	Specifies the next request section when data is found. The value of this parameter is a string, name. The name specifies an LDAP Search request by referencing a [Search/name] section elsewhere in the same `.gen` file. If there is no next request section, the overall operation succeeds.
OnNotFound	Specifies the next request section when data is not found. The value of this parameter is a string, `name`. The `name` specifies an LDAP Search request by referencing a [Search/name] section elsewhere in the same `.gen` file. If there is no next request section, the overall operation fails.
Filter	Specifies the filter to apply to the search. This filter is a template for an LDAP Search string. The filter follows conventional LDAP syntax and may be as simple or as complex as LDAP syntax permits, with multiple attribute/value assertions in Boolean combination. It may also include replacement variables from the Variable Table. Each replacement variable consists of the variable name enclosed in angle brackets (<>). Upon execution of the LDAP Search request, the value of the variable replaces the variable name. For example, a Search template that uses the `User-Name` and `Service-Type` attributes from the RADIUS request might look like this: (&(uid = <User-Name>)(type = <Service-Type>))
Scope	Specifies the scope of the search; 0 (search the base), 1 (search all entries one level beneath the base), or 2 (search the base and all entries beneath the base at any level).

The OnFound and OnNotFound parameters can be used in [Search/name] sections to create serial chains of search requests. The OnFound parameter specifies the name of a search to try if the current search returns a non-empty result from the LDAP repository. The OnNotFound parameter specifies the name of a search to try if the current search fails to return data. Arbitrarily complex search trees may be created.

This example shows a simple LDAP search tree:

[Request] Section

The [Request] section provides the LDAP data accessor with the names of variables to create in the input variable container. It also indicates to the data accessor which input variable container entries to copy to the internal variable table before execution of the LDAP search request tree.

Where invar is the name of a variable in the input variable container and tablevar is the name of an entry in the internal variable table.

tablevar may be omitted from any [Request] entry. If so, the variable in the input variable container is copied to an internal variable table entry named invar.

[Defaults] Section

The [Defaults] section of the LDAP data accessor configuration file enables you to add named entries to the internal variable table before the LDAP search tree is executed. You can reference these variables in your queries, even if they are not initialized from the [Request] section.

The format of each [Defaults] entry is:

Where tablevar is the name of a variable in the internal variable table and value is the value you want to assign to it. For example:

[Server/name] Sections

Several sections of the LDAP data accessor file work together to configure the connection between the Steel-Belted Radius Carrier server and the LDAP database server(s). The sections are: [Server], [Server/name], and [Settings].

Each [Server/name] section of the LDAP data accessor file contains configuration information about a single LDAP server. You must provide a [Server/name] section for each server you named in the [Server] section (Table 135). For example:

Table 135: *.gen [Server/name] Syntax

Parameter	Function
BindName	The BindName parameter specifies the distinguished name (DN) to be used to connect to the LDAP server. In [Server/name] section, specify a unique BindName for a specific server. Use the [Settings] section to specify a default BindName to use for all servers.
BindPassword	The BindPassword specifies the password to be used to connect to the LDAP server. In [Server/name] section, specify a unique BindPassword for a specific server. Use the [Settings] section to specify a default BindPassword to use for all servers.
Certificates	Specifies the path of the certificate database for use with SSL. This path must not end in a filename.
ConnectTimeout	Specifies the number of seconds to wait when attempting to establish the connection to the database before timing out. This value is passed to the client database engine, which may or may not implement the feature.
FlashReconnect	If the server is down when performing a Search, setting this parameter to 1 triggers a reconnection attempt before rejecting the request. Therefore, requests are not rejected due to inactivity timeouts. This setting applies to a particular server. To apply it for all servers, place it in the [Settings] section.
Host	The hostname or IP address of the LDAP server. Note: For SSL configurations, the hostname accepts only LDAP-style URIs. For example, ldaps://hostname:port.
LastResort	You may identify a last resort LDAP server by providing a LastResort parameter in one of these [Server/name] sections, and setting its value to 1. If the search returns no result, the execution of the search tree completes (unless OnNotFound is configured).
LdapVersion	Specifies the version of LDAP protocol, if needed to override the default given in the [Settings] section.
MaxConcurrent	Specifies the maximum number of instances of a single LDAP request that may be executing at one time.
MaxWaitReconnect	Specifies the maximum number of seconds to wait after successive failures to reconnect after a failure of the database connection. WaitReconnect specifies the time to wait after failure of the database connection. This value is doubled on each failed attempt to reconnect, up to a maximum of MaxWaitReconnect.
Port	The TCP port of the LDAP server, or 0 to use the standard port. Default value is 0. Note: For SSL configurations, the default port setting is ignored and the LDAP-style URIs for Host is applied. For example, ldaps://hostname:port.
QueryTimeout	Specifies the number of seconds to wait for the execution of an LDAP request to complete before timing out. This value is passed to the database engine, which may or may not implement the feature.
Search	The value of this parameter is a string, `name`. The `name` specifies an LDAP Search request by referencing a [Search/name] section elsewhere in the same `.gen` file.
SSL	If set to 0, SSL is not used over the LDAP connection. If set to 1, SSL is used over the LDAP connection. Default value is 0.
WaitReconnect	Specifies the number of seconds to wait after a failure of the database connection before trying to connect again.

[Server] Section

The [Server] section (Table 136) of the LDAP data accessor configuration file lists the LDAP servers. You can specify more than one server in the [Server] section for load-balancing or backup. When more than one server is specified, Steel-Belted Radius Carrier authenticates against these databases in a round-robin fashion.

The syntax is as follows:

Where ServerName is the name of a header file section that contains configuration information for that server, and TargetNumber is an activation target number, a number that controls when this server is activated for backup purposes. TargetNumber is optional and may be left blank. For example:

A Steel-Belted Radius Carrier server maintains connectivity with its LDAP servers according to these rules:

The priority of the server by order. The first entry in the [Server] section has the highest priority.
By activation target number. The rule for the activation target is that if the number of LDAP servers that Steel-Belted Radius Carrier is connected to is less than the activation target, Steel-Belted Radius Carrier connects to the server and includes it in the round-robin list. While the number of active servers is equal to or greater that the activation target, Steel-Belted Radius Carrier does not use that server in the round-robin list. An activation target of 0 indicates that, in the current configuration, this machine is never used.

[Settings] Section

The [Settings] section (Table 136) of the LDAP data accessor configuration file forms a basis for all Search requests to the LDAP database servers.

The values set in [Settings] for some parameters, such as ConnectTimeout, MaxConcurrent, or WaitReconnect, provide defaults that apply to all servers. These default values can be overridden for a particular server by entering the same parameter with a different value in a [Server/name] section.

Table 136: *.gen [Settings] Syntax

Parameter	Function
BindName	In the [Settings] section, BindName and BindPassword specify a default LDAP template to use for all servers. You can also use BindName and BindPassword in [Server/name] sections to override this default for an individual server.
ConnectTimeout	Specifies the number of seconds to wait when attempting to establish the connection to the database before timing out. This value is passed to the client database engine, which may or may not implement the feature. Default value is 25 seconds.
FilterSpecial CharacterHandling	If set to 1, specifies that non-alphanumeric characters, such as (or), should be converted to an ASCII hex value preceded by a backslash when they are encountered in a username. If set to 0, non-alphanumeric characters are not converted. Default value is 0.
FlashReconnect	If the server is down when performing a Search, setting this parameter to 1 triggers a reconnection attempt before rejecting the request. Therefore, requests are not rejected due to inactivity timeouts. Note: The value specified in this parameter can be overridden in individual [Server/name] sections of this file.
LdapVersion	Specifies the version of LDAP protocol. Default value is 2.
LogLevel	Activates logging for the LDAP data accessor and sets the rate at which it writes entries to the Steel-Belted Radius Carrier server log file (.LOG). This value may be the number 0, 1, or 2, where 0 is the lowest logging level, 1 is intermediate, and 2 is the most verbose. If the LogLevel that you set in the `.gen` file is different than the LogLevel in radius.ini, the radius.ini setting determines the rate of logging. The LogLevel is re-read whenever the server receives a SIGHUP (1) signal.
MaxConcurrent	Specifies the maximum number of instances of a single LDAP request that may be executing at one time. Note: The value specified in this parameter can be overridden in individual [Server/name] sections of this file.
MaxWaitReconnect	Specifies the maximum number of seconds to wait after successive failures to reconnect after a failure of the database connection. WaitReconnect specifies the time to wait after failure of the database connection. This value is doubled on each failed attempt to reconnect, up to a maximum of MaxWaitReconnect. Note: The value specified in this parameter can be overridden in individual [Server/name] sections of this file.
OnFound	Specifies the next request section when data is found. The value of this parameter is a string, `name`. The `name` specifies an LDAP Search request by referencing a [Search/name] section elsewhere in the same `.gen` file. If there is no next request section, the overall operation succeeds.
OnNotFound	Specifies the next request section when data is not found. The value of this parameter is a string, `name`. The `name` specifies an LDAP Search request by referencing a [Search/name] section elsewhere in the same `.gen` file. If there is no next request section, the overall operation fails.
QueryTimeout	Specifies the timeout value in seconds for an individual search performed against the LDAP server. Default value is 10 seconds.
Search	The value of this parameter is a string, `name`. The `name` specifies an LDAP Search request by referencing a [Search/name] section elsewhere in the same `.gen` file.
SSL	If set to 0, SSL is not used over the LDAP connection. If set to 1, SSL is used over the LDAP connection. Default value is 0. Note: The value specified in this parameter can be overridden in individual [Server/name] sections of this file. If SSL=1, the Host parameter in [Server/`name`] accepts only LDAP-style URIs. For example, ldaps://hostname:port.
WaitReconnect	Specifies the number of seconds to wait after a failure of the database connection before trying to connect again.
Timeout	Specifies the maximum number of seconds for the overall timeout for each request, which includes the delay in acquiring resources, attempts against multiple LDAP servers, and so forth. Default value is 20 seconds.
UTC	If set to 0, time values are displayed using the local time. If set to 1, time values are displayed using universal time coordinates (UTC).
WaitReconnect	Specifies the number of seconds to wait after a failure of the database connection before trying to connect again. Note: The value specified in this parameter can be overridden in individual [Server/name] sections of this file.

[VariableTypes] Section

The [VariableTypes] section of the LDAP data accessor configuration file specifies the storage data type for each entry in the input and output variable containers.

where variable is the name of an input or output container variable and type is the data type specifier, one of string, binary, integer, ipaddress, ipv6address, ipv6prefix, ipv6interface, or date.

For more information about selecting the variable type specifier, see Data Conversion Rules.