Common Configurations

This section explains the common configurations of LDAP plug-ins.

[Bootstrap] Section

The [Bootstrap] section (Table 156) of the LDAP configuration file specifies information that Steel-Belted Radius Carrier uses to load and start the LDAP method.

Table 156: [Bootstrap] Syntax

Parameter	Function
LibraryName	Specifies the name of the LDAP module, for example, ldapauth.so or ldapaccessor.so.
Enable	If set to 1, the LDAP module is enabled. If set to 0, the LDAP module is disabled. Default value is 0.
InitializationString	Specifies the identifier for the LDAP module. The name of each LDAP module must be unique. Default value is LDAP.

Parameter

Function

LibraryName

Specifies the name of the LDAP module, for example, ldapauth.so or ldapaccessor.so.

Enable

If set to 1, the LDAP module is enabled.
If set to 0, the LDAP module is disabled.

Default value is 0.

InitializationString

Specifies the identifier for the LDAP module.

The name of each LDAP module must be unique.

Default value is LDAP.

[Settings] Section

The [Settings] section of the LDAP configuration file forms a basis for all Bind and Search requests to the LDAP database server(s).

Search sequencing is flexible. You can override search results using the $reject and $accept keywords.

You can proceed to a new search even if the current search returns no data by using the OnNotFound parameter.

For examples of using flexible searching, see [Server/name] Sections.

The parameters in the [Settings] section apply to all LDAP servers listed in the configuration file. The following parameters are usually present. If any of these parameters is not provided in the [Settings] section, the parameter assumes a system default value.

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 157: [Settings] Syntax

Parameter	Function
MaxConcurrent	Specifies the maximum number of LDAP requests that may be executing at one time. You can enter the value in the range from 1 through 500. Default value is 1. Note: The value specified in this parameter can be overridden in individual [Server/`name`] sections of this file. Note: A setting of `MaxConcurrent = 1` is sufficient for all but the most demanding environments. Increase this value slowly and conservatively. For more information about executing overlapping LDAP statements, see the SBR Carrier Administration and Configuration Guide.
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.
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. Note: The value specified in this parameter can be overridden in individual [Server/`name`] sections of this file.
QueryTimeout	Specifies the timeout value in seconds for an individual search performed against the LDAP server. Default value is 10 seconds.
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.
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.
BindName	For `BindName`, you must omit the Bind parameter from the LDAP configuration file. Use the `BindName` and `BindPassword` parameters instead. In the [Settings] section, `BindName` and `BindPassword` specify a default LDAP Bind 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 See [Server/name] Sections.
LogLevel	Activates logging for the LDAP method and sets the level of detail of the message. 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 configuration file is different than the `LogLevel` in `radius.ini`, the lower value of the setting controls.
UpperCaseName	If set to 0, preserves the case of the username. If set to 1, converts the username to uppercase. Default value is 0.
PasswordCase	If set to U or Upper, the password returned from the LDAP database is converted to uppercase before authentication. If set to L or Lower, the password is converted to lowercase. If set to O or Original, the password is not altered before authentication. Default value is Original.
PasswordFormat	By default, the `PasswordFormat` parameter is not listed in the [Settings] section of the LDAP configuration file. With no listing, Steel-Belted Radius Carrier expects the user's password in the LDAP table is in cleartext format. If you want to configure Steel-Belted Radius Carrier to automatically handle password values correctly when it detects that they have been encrypted using UNIXcrypt or a SHA1+Base64 hash, set `PasswordFormat` to auto.
Search	Specifies an LDAP Search request by referencing a [Search/`name`] section elsewhere in the same `*.aut` 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, then the Host parameter in [Server/`name`] accepts LDAP-style URIs. For example, ldaps://hostname:port.
MaxScriptSteps	Specifies the maximum number of statements that a script can execute before terminating. You can use the `MaxScriptSteps` parameter to make sure a script does not get caught in an infinite loop. Default value is 10000.
ScriptTraceLevel	Specifies the level of detail for line-by-line script tracing in the log. If set to 0, no traces are logged. If set to 1, traces are only logged when the `SbrTrace()` function is executed by the script. If set to 2, a trace is generated for every line executed by the script. Default value is 0.
ShutdownTimeout	Specifies the maximum number of seconds to wait for outstanding database transactions when the server is in the process of shutting down. If this timeout expires, then any outstanding database transactions are forcibly terminated in order to allow the server to shut down. Default value is 180 seconds. Note: Changing the default value is not recommended.
FilterSpecial CharacterHandling	If set to 1, specifies that non-alphanumeric characters, such as (’), is converted to an ASCII hex value preceded by a backslash when they are encountered in a username during authentication. If set to 0, non-alphanumeric characters are not converted during authentication. Default value is 1. In support of RFC 2254, the following substitutions are made when set: replace '(' with "\\28" replace ')' with "\\29" replace '*' with "\\2a" replace '\' with "\\5c"
FlashReconnect	If set to 1, SBR Carrier attempts to reconnect to an LDAP database server when the LDAP database server goes down. When this setting is enabled, SBR Carrier immediately attempts to reconnect to the LDAP database server if a Bind or a Search operation fails and sends an Access-Reject if the connection attempt is unsuccessful. Note: If SBR Carrier has not successfully connected to the LDAP database server since startup, SBR Carrier directly rejects the request without performing any Bind or Search operation even if this parameter is set to 1. If set to 0, SBR Carrier sends an Access-Reject before the reconnection is attempted. This setting applies to all servers. To apply this setting for a particular server, configure the `FlashReconnect` parameter in the [Server/`name`] section. Default value is 1.
LdapVersion	Specifies the version of LDAP protocol. Default value is 2.
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 `.aut` file. If there is no next request section, the overall operation succeeds. This can be overridden using the `$reject` keyword, which causes the operation to fail when data is found.
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 `.aut` file. If there is no next request section, the overall operation fails. This can be overridden using the `$accept` keyword, which causes the operation to succeed when data is not found.
Password	Specifies the password string, which can include variables, used to specify a Bind before any search within a request. If this parameter is not specified, the packet's password is used.
UTC	If set to 0, time values are displayed using the local time. If set to 1, time values are displayed using UTC (GMT).

[Server] Section

The [Server] section lists the LDAP servers that may be used to perform authentication. 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:

where ServerName is the name of a configuration 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 the following 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.

[Server/name] Sections

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

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

Table 158 lists the settings that may be present in a [Server/ name ] section:

Table 158: [Server/name] Syntax

Parameter	Function
Bind	For Bind, you must specify a Bind template in the [Settings] section of the LDAP configuration file. The Bind template must follow conventional LDAP syntax. It 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 Bind request, the value of the variable replaces the variable name. For example, a Bind template that uses the User-Name attribute from the RADIUS request might look like this: `uid=<User-Name>, ou=Special Users, o=bigco.com`
BindName	For BindName, the `BindName` parameter specifies the distinguished name (DN) to be used in the Bind request that connects to the LDAP server. The [Server/`name`] section lets you specify a unique `BindName` for a specific server. Use the [Settings] section to specify a default `BindName` to use for all servers. For Bind, omit all `Bind`, `BindName` and `BindPassword` parameters and use the `Bind` parameter in the [Settings] section. See [Settings] Section.
BindPassword	For BindName, you must provide a `BindPassword`. The `BindPassword` specifies the password to be used in the Bind request that connects to the LDAP server. The [Server/`name`] section lets you specify a unique `BindPassword` for a specific server. Use the [Settings] section to specify a default `BindPassword` to use for all servers. For Bind, omit the `BindName` and `BindPassword` parameters. Use the `Bind` parameter instead.
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 set to 1, SBR Carrier attempts to reconnect to an LDAP database server when the LDAP database server goes down. When this setting is enabled, SBR Carrier immediately attempts to reconnect to the LDAP database server if a Bind or a Search operation fails and sends an Access-Reject if the connection attempt is unsuccessful. Note: If SBR Carrier has not successfully connected to the LDAP database server since startup, SBR Carrier directly rejects the request without performing any Bind or Search operation even if this parameter is set to 1. If set to 0, SBR Carrier sends an Access-Reject before the reconnection is attempted. This setting applies to a particular server. To apply this setting for all servers, configure the `FlashReconnect` parameter in the [Settings] section. Default value is 1.
Host	The hostname or IP address of the LDAP server. Note: For SSL configurations, the host name field 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 an LDAP query against some other server results in `no record` found, the server tries the last resort server before accepting or rejecting the user. You might use the `LastResort` parameter to identify your primary accounts database. This enables Steel-Belted Radius Carrier to cover the case in which a user account is newly added but has not yet been propagated to all the LDAP databases.
LdapVersion	Specifies the version of LDAP protocol, if needed to override the default given in the [Settings] section.
MaxConcurrent	Specifies the maximum number of LDAP requests that may be executing at one time. You can enter the value in the range from 1 through 1000. Default value is 1. Note: A setting of `MaxConcurrent = 1` is sufficient for all but the most demanding environments. Increase this value slowly and conservatively. For more information about executing overlapping LDAP statements, see the SBR Carrier Administration and Configuration Guide.
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`.
Password	Specifies the password string, which can include variables, used to specify a Bind before any search within a request. If this parameter is not specified, the packet's password is used.
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 URI 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.
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.

[Search/DoLdapSearch] Sections

Each [Search/name] section (Table 159) in the LDAP configuration file specifies the complete details of one LDAP Search request. You can use the same Search request on various databases, because the details of the database connection are specified separately.

For BindName, you must ensure that each [Search/name] section searches for a database entry that matches the incoming username and retrieves from it an attribute containing that user’s password. Steel-Belted Radius Carrier must compare this password to the one it received in the incoming AccessRequest packet.

A [Search/name] section may retrieve other LDAP attributes as well; however, if you are authenticating with BindName, the user’s password is a minimum requirement. Use the Attributes parameter to specify the list of items you want returned.

For example:

Table 159: [Search/name] Syntax

Parameter	Function
%DN	Specifies a variable into which the distinguished name that results from the Search is placed.
Attributes	Specifies the LDAP attributes relevant to Steel-Belted Radius Carrier, by referencing an [Attributes/`name`] section elsewhere in the same `.aut` 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 `.aut` file. If there is no next request section, the overall operation succeeds. This can be overridden using the `$reject` keyword, which causes the operation to fail when data is found.
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 configuration file. If there is no next request section, the overall operation fails. This can be overridden using the `$accept` keyword, which causes the operation to succeed when data is not found.
Search	(Optional) Specifies an LDAP Search request by referencing a [Search/`name`] section elsewhere in the same configuration file. Steel-Belted Radius Carrier tries this Search request next, if the current Search yields no result. Each [Search/`name`] section may contain at most one Search parameter.
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 Search parameter can be used in one [Search/ name ] section after another to create a serial chain of Search requests. Every Search in the chain is tried. If any Search fails to return data, the Access-Request is rejected.

An example of a two-part chained Search follows:

Search sequencing is flexible. You can proceed to a new search even if the current search returns no data by using the OnNotFound parameter. You can override search results using the $reject and $accept keywords. The following is an example of flexible searching: